Move NESTML documentation to ReadTheDocs

[clinssen]

This PR adds the necessary files to make NESTML API documentation render on readthedocs.org.

Please see the rendered results (based on my personal fork) at: https://nestml-api-documentation.readthedocs.io/

The public-facing version of the documentation will be at https://nestml.readthedocs.io/

Sphinx is a little obtuse when it comes to the organisation into modules/submodules/packages. We therefore have limited room to play around with this. My current strategy is to have a minimal landing page, with a single link to the "pynestml" package, which then lists all subpackages and -modules. Is this acceptable to the reviewers?

Some rendering errors exist when converting the ReST-style docstrings to HTML. This will of course be addressed, but I would like to do this in a separate PR, where we can then tackle the specification of parameter and return types at the same time.

Open question: should we consistently refer to PyNESTML API documentation, as these documents pertain more to the toolchain than the language itself?

N.B. please squash these commits when merging!

[Silmathoron]

Ah, sorry, I completely forgot I said I would take care of that...
Thanks for doing it then ^^"
Couple of remarks:

1. I think we should distinguish between the language and the API so I would leave out the Py
2. I really think RtD should include a doc that would actually be useful to human beings (a raw API seldom is) so I would prefer if we made the current doc more readable and prettier by moving it to RST and including it in RtD
3. I did not get that:

Sphinx is a little obtuse when it comes to the organisation into modules/submodules/packages

No it's not, that's its main purpose so you can make it do pretty much anything ^^ what did you want to do ?

[clinssen]

Hi @Silmathoron, thanks for your thoughts. At some point during coding I just really wished I had the HTML API docs nearby; already forgot that we talked about it before!

Re the distinction between NESTML and PyNESTML: should this API doc then not be called "PyNESTML API documentation", rather than "NESTML API documentation", as it pertains to the toolchain and not the language?

As for human-written docs: I want to prevent the fragmentation of documents across too many places. This is why I suggested to keep the readthedocs page strictly for the API docs. Of course we can still do a lot better there by adding introductory text to the main modules (e.g. in meta_model/__init__.py, write what the meta model directory is for, and so on). However, as a future extension, we could also automatically render the ReST/MarkDown files in doc/ on readthedocs. Then they would always be synchronous.

[jessica-mitchell]

@clinssen

• I noticed that some APIs have ellipses, where I assume some text will replace this at a later time?

• A lot of the listed functions and classmethods contain no information (e.g.https://nestml-api-documentation.readthedocs.io/en/latest/pynestml.symbols.html#pynestml.symbols.predefined_functions.PredefinedFunctions) - not sure if these need to be here, should contain more information, or fine the way they are.

• Some links contain empty files (e.g., https://nestml-api-documentation.readthedocs.io/en/latest/pynestml.codegeneration.resources_nest.setup.html and https://nestml-api-documentation.readthedocs.io/en/latest/pynestml.codegeneration.resources_nest.directives.html)

• It looks to me that a lot of the markup is not generating properly

  • like properties are not being displayed properly (e.g, see screenshot)

I would expect the :text: to be marked up differently. I'm not sure if the proper terms are being used here.

• Some other output that looks strange:

https://nestml-api-documentation.readthedocs.io/en/latest/pynestml.generated.html#pynestml.generated.PyNestMLLexer.PyNestMLLexer.symbolicNames

• Who is the intended audience? This feels like an internal reference file, which would only be suitable for those who know what's going on with the code.

[clinssen]

A custom Pygments lexer was added to enable NESTML syntax highlighting on readthedocs.

[abigailm]

Merging after live review