Integrate sphinx to read .xml documentation from Visual Studio

[Nikhil-42]

Installs Vsxmd into Visual Studio so that developers may generate consistent .md documentation from docstrings.
Automatically copies .md files from crest/crest/Temp/bin/Debug/ into crest/docs/api/ (fails gracefully if files not present)
Adds recommonmark to parse .md files

The developer still has to manually configure Visual Studio to generate XML documentation after which they must perform a build, Vsxmd will kick in automatically and build the .md

[Nikhil-42]

Is there a timeline on when this can get merged?

[huwb]

I dont understand this pr, but might have missed the conversation/context, apologies if so. im pretty sure dale would be much better equipped to understand this, but for now you have me so brace for dumb questions :):

Do we have docstrings? Is it the /// syntax in c#? Is this PR proposing that we start generating docs from code comments?

Do we want to generate md files, in light of RTD? (or to take a step back - how does this relate or not relate to the RTD work?)

Apologies again that i have not understood this, i did read it a couple of times but i have no experience in this area.

[daleeidd]

Do we have docstrings? Is it the /// syntax in c#?

We do. It is with the XML (/// <summary> etc).

Is this PR proposing that we start generating docs from code comments?

Yes.

Do we want to generate md files, in light of RTD? (or to take a step back - how does this relate or not relate to the RTD work?)

RTD uses Sphinx/DocUtils which can use multiple parsers. We are using RST (reStructuredText) but we can also use MD (we can use both together). Using MD here is just what the VS utility uses.

This is the API docs so it covers using Crest for scripting which we don't currently document. This would only cover BIRP.

Is there a timeline on when this can get merged?

Not really unfortunately. PRs can sit here for a while. It will probably have to wait until after Crest 4.9 (which should be soon).

[Nikhil-42]

@huwb Sphinx is the documentation engine that RTD uses to build documentation pages. Sphinx uses a custom markup language known as ReStructuredText (.rst), however, with the ReCommonMark plugin they do officially support Markdown (.md)

We already have docstrings. They are the /// syntax in C#. This PR uses a Visual Studio plugin Vsxmd to build a Markdown documentation file when the project is built in Visual Studio. The only reason to use Markdown here is because I couldn't find a plugin that generates ReStructuredText.

Basically, this PR builds an API reference using all the /// comments we've been writing all along and puts it into the RTD webpage.

To be honest, it's kind of Frankencode that just glues some libraries together and produces a good enough result.

It can most definitely be improved upon.

Side Note: I don't particularly like how Vsxmd formats things but that's personal perference.

[huwb]

So when we are building a PDF, it will generate API docs into it?

And it also appears in the RTD webpage - does it need a build step to get it in or does RTD automagically pull in the latest docs?

BIRP only - i think i understand why. @daleeidd is this still worth pursuing? would it only cover the public API (i realise right now everythings public)? if it was public api only that might be fairly consistent across RPs i guess?

[Nikhil-42]

@huwb I believe @daleeidd wanted to prevent the API docs from building into the PDF for bloat reasons. to make this useful it should definitely add a build step. right now you have to manually build from visual studio before pushing to GitHub for RTD to pick it up.

rn im working on integrating it into the build Makefile and removing dependency on vsxmd

[daleeidd]

@nikhil-work
It's a shame that sphinx-autoapi (uses https://dotnet.github.io/docfx/ which is a bit more portable) doesn't support our version of sphinx. The ideal would have been to have RTDs to generate the files for us on their server. But the C# version of sphinx-autoapi is outdated and I don't even know if RTDs properly supports that scenario even if it did.

BIRP only - i think i understand why. @daleeidd is this still worth pursuing? would it only cover the public API (i realise right now everythings public)? if it was public api only that might be fairly consistent across RPs i guess?

@huwb
That sounds about right. I think it is worth pursuing based on a benefit it would bring. There are some comments which we wouldn't want in the docs like some of the ASCII art geometry diagrams. But not a major issue. Providing that the workflow can be worked out well (automated somehow hopefully), then it will be great to have.