using Doxygen in read-the-docs

Question

I have written the documentation for a medium sized C++ piece of software using Doxygen together with Markdown. I am quite happy with it, as after changing the xml layer I ended up with something like that: http://docs.mitk.org/nightly/index.html

I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation would be automatically built after a "git commit", and hosted to be browsed.

ReadtheDocs looks like the ideal site but uses Sphinx and reStructuredText as defaults. Doxygen can be used too, but AFAIK only through Breathe. Going through that route essentially means that I would need to re-structure all the documentation if I don't want to dump all the API documentation into a single page (http://librelist.com/browser//breathe/2011/8/6/fwd-guidance-for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project/#cab3f36b1e4bb2294e2507acad71775f).

Paradoxically, Doxygen is installed in the read-the-docs server, but after struggling I could not find a workaround to skip its Sphinx or Mkdocs.

Answer 1

This answer builds upon the great one already given by "kzeslaf". So follow the steps described by him first, before you continue here.

While his answer works as intended, I had the problem that ReadTheDocs (RTD) uses a rather old version of Doxygen (1.8.13 at the time of writing). This caused several issues for me like the one reported here. Additionally, if you set up Doxygen to treat warnings as errors, you might need to override this option on RTD due to version-related warnings.

I found a simple solution to upgrade the Doxygen version on RTD using conda. Create an environment.yml file somewhere in your project (probably in the documentation directory). The content is as follows:

name: RTD
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.8
  - doxygen=<VERSION>

Replace <VERSION> with any version number that you like to use and that is available on conda-forge. Use conda search doxygen -c conda-forge to get a list of all available versions or simply check this site. You can also remove =<VERSION> and conda should install the latest one automatically.

Now you need to create an RTD config file if you haven't done this already. Add the following lines:

conda:
  environment: <DIRECTORY>/environment.yml

Replace <DIRECTORY> with the actual location of the environment.yml file (relative to your project root, for example: docs/environment.yml). Now, if you followed all the steps in the answer of "kzelaf" and the ones I mentioned, RTD should successfully build your Doxygen documentation with the version you selected. You can check it in the lower right corner of the created pages. Alternatively, add subprocess.run(["doxygen", "-v"]) to your conf.py and check the RTD build logs.

Answer 2

I've tried the following solution to use Doxygen on Read The Docs and it seems to work:

1. set up empty sphinx project (refer to official sphinx doc),
2. in sphinx conf.py add command to build doxygen documentation,
3. use conf.py html_extra_path config directive to overwrite generated doxygen documentation over generated sphinx documentation.

I've tested this with following source tree:

.../doc/Doxyfile
       /build/html
       /sphinx/conf.py
       /sphinx/index.rst
       /sphinx/...

Some explanation:

1. in my setup doxygen generates its documentation in "doc/build/html",
2. ReadTheDocs runs its commands in directory where it finds conf.py file.

What to do:

1. add following lines in conf.py to generate doxygen docs:

    import subprocess
    subprocess.call('cd .. ; doxygen', shell=True)
   

2. update conf.py html_extra_path directive to:

    html_extra_path = ['../build/html']
   

In this configuration ReadTheDocs should properly generate and store Doxygen html documentation.

todo:

• other documentation formats, for example: pdf.