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.

Whistler

Answer 1

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.

Eldred

Yes, it worked like charm, many thanks. On another note, I use CMake to configure a number of files, and would be nice if it were installed in the readthedocs server. For the moment, I re-coded this configuration within conf.py, though having CMake would be great not to maintain two pieces of software doing the same. – Whistler

The method above is also documented here: breathe.readthedocs.io/en/latest/readthedocs.html – Fromma

make sure to look into this blog post devblogs.microsoft.com/cppblog/… – Dinky

Great answer. The html_extra_path bit to copy the Doxygen doc over the Sphinx doc to make it work on the Readthedocs site is... happy magic! – Lurcher

I always got a default home page(from unmodified index.rst) and could not see any of the html pages, do I need update index.rst somehow before the 'make html' – Sovereign

I'm also not seeing anything from the doxygen on readthedocs homepage. I can confirm the files are generated by doxygen and copied, cause when I download the zippedhtml from RTD all files are there, incl index.html – Bureau

Answer 2

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.

Contemporaneous