[dev] Publishing documentation to readthedocs.org (from Github Actions?)

[pramodk]

Motivation : Multiple projects like NEURON, CoreNEURON and NMODL builds documentation as part of Travis or Github Actions (very recently). This documentation is pushed to GitHub.io (e.g. NEURON doc here, NMODL doc here; I am seeing an error for CoreNEURON somehow).

One of the drawback of GitHub.io is that we can store only single snapshot at a time (without hack of branches). More elegant way is to use readthedocs.org where versioning and other aspects are managed very nicely!

So it will be helpful if we could investigate readthedocs.org option and successfully migrate one of the project.

Action Items:

• Check possibility of connecting Github Actions with readthedocs.org
• IIRC, readthedocs.org has an option to configure project where one can build the documentation on the readthedocs.org itself. Investigate what are options and best approaches.
• NOTE : there is one caveat I remember with above approach: for some projects setting up readthedocs.org configuration and building project like NMODL is not easy : 1. needed quite some build dependencies 2. need to build entire project to build full docs 3. also need to execute Jupyter notebooks (see here). This is quite cumbersome ~2 years ago. And thats why if we can use GitHub Actions setup, that would be less hassle (?)

cc: @tristan0x @matz-e @alkino @alexsavulescu

[alkino]

Publish sphinx and doxygen doc or only sphinx?

[tristan0x]

• Hosting the documentation on readthedocs is the preferred solution according to the BlueBrain software development guidelines.
• +1 to provide documentation for several versions.
• +1 to let readthedocs builds the documentation because having an external entity to build it ensures it can be done seamlessly. It also removes the burden of maintaining the build automaton ourself.

[matz-e]

• +1 to let readthedocs builds the documentation because having an external entity to build it ensures it can be done seamlessly. It also removes the burden of maintaining the build automaton ourself.

I like this, although I'm curious about the implications of relying on breathe/exhale/all this doxygen-sphinx glue?

[alkino]

• +1 to let readthedocs builds the documentation because having an external entity to build it ensures it can be done seamlessly. It also removes the burden of maintaining the build automaton ourself.

I like this, although I'm curious about the implications of relying on breathe/exhale/all this doxygen-sphinx glue?

There is no doxygen-sphinx glue here, because we compile both separately and there is only a link from the sphinx documentation to the doxygen documentation.

[alexsavulescu]

Yes, there is no doxygen integration. CoreNEURON documentation is rather new and lacks substance. While breathe+exhale sound nice on paper, they are just extremely slow with NEURON.

I am seeing an error for CoreNEURON somehow).

@pramodk URI is case sensitive: http://bluebrain.github.io/CoreNeuron/

[pramodk]

+1 to let readthedocs builds the documentation because having an external entity to build it ensures it can be done seamlessly. It also removes the burden of maintaining the build automaton ourself.

(This was discussed bit in #coreneuron Slack channel. Here is short summary)

@tristan0x : About building project on readthedocs:

I mentioned the caveat in the description. When we were setting up documentation for NMODL project, almost ~2 years ago, I couldn't easily setup all build dependencies like flex, bison, cmake etc (readthedocs/readthedocs-docker-images#114).

We needed to build nmodl python library in order to build documentation + compile Jupyter notebooks. Read-the-docs default workflow was not providing that much flexibility and hence we decided to use GitHub.io.

Looking at newer issues (readthedocs/readthedocs.org#6919, readthedocs/readthedocs.org#5387 (comment)), there seems to be two ways install dependencies : 1) conf.py (hack) 2) conda config yaml

If above things work without too much trouble (or efforts), we can use above approach. Otherwise, we can think about simplified approaches.

[alkino]

See #462