Make Doxygen developer documentation available via readthedocs

[jougs]

Before #1843, NEST used the Breathe extension for Sphinx to extract the Doxygen code comments from the source base. However, the extracted information was not (and still isn't) shown on Read the Docs.

The main task for solving this issue is to decide how and where in the documentation to display the developer level information and making the necessary changes to the configuration and build system. Activating the Breathe extension itself involves the following steps:

1. Adding a Doxyfile to the doc directory. See here for the version that was removed in Fix doc buildsystem #1843.
2. Adding "breathe" to the extensions list defined in doc/conf.py:L117
3. Configuring Breathe in doc/conf.py:

   breathe_projects = {"EXTRACT_MODELS": build_path / "doc/breathe/doxygen/EXTRACT_MODELS/xml"}
   breathe_projects_source = {"EXTRACT_MODELS": (root_path / "doc", list(root_path.rglob('*.h')))}
   breathe_default_project = "EXTRACT_MODELS"
   
   # I'm not sure if the following is actually needed...
   subprocess.call('doxygen', shell=True)

4. Adding a Breathe directive to one or more RST files in the documentation. An example might be

   .. autodoxygenindex::
      :project: EXTRACT_MODELS

---

This issue might or might not have a connection to some of the action items in #1659.

[jessica-mitchell]

Hi
I was just taking a look at this again and tested the workflow to refresh my memories on how this all worked.

Considering the changes to how the docs will be built after #1843 , I was wondering if it made sense to do the following

1. Reduce make doc and make html so there is only one make for documentation. So all documentation is output to RtD
2. Take the configuration in normaldoc/fulldoc (not sure what the difference is) that generates html from doxygen and change it to generate xml, the format breathe needs
3. set up sphinx conf as mentioned above + modify rst files for nice output
4. get it working on readthedocs

I wanted to try out the process (in a very rough fashion) so I created a branch based off of @jougs' branch for #1843. I then modified the normaldoc file, so running make doc generates xml and after adding the necessary breathe config, running make html produces the doxygen output from the xml. So obviously not a nice solution but a start.

Of course the other problem mentioned is not getting output on ReadtheDocs
So I tested this as well, but using a Doxyfile inside the doc source folder for simplicity.
and I got this from ReadtheDocs: https://nest-test.readthedocs.io/en/test-breathe-again/dev_docs.html
I was expecting the build to fail so I was surprised that it worked on first go.

So that's what I have so far. @jougs @steffengraber what do you think?

[jougs]

1. Reduce make doc and make html so there is only one make for documentation. So all documentation is output to RtD

Please see #1905 for a proposal related to this

2. Take the configuration in normaldoc/fulldoc (not sure what the difference is) that generates html from doxygen and change it to generate xml, the format breathe needs

Also see #1905. And I like your proposal regarding XML as the intermediate format

[github-actions]

Issue automatically marked stale!

[jessica-mitchell]

This issue should wait until #2560 is merged becaue it makes huge changes to the conf.py file and affects the build of the docs.