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

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.