Geek Answers Handbook

Using Doxygen in read-the-docs

I wrote documentation for the mid-sized C ++ piece of software using Doxygen with Markdown. I am quite happy with this, because after changing the xml layer I got something like this: http://docs.mitk.org/nightly/index.html

I would like to bring this documentation online, ideally using something like ReadtheDocs, where the documentation will be automatically built after the "git commit" and posted for viewing.

ReadtheDocs looks like a perfect site, but uses Sphinx and reStructuredText as default values. Doxygen can also be used, but AFAIK only through Breathe. Passing this route essentially means that I will need to restructure all the documentation if I do not want to upload all the API documentation to one page ( http://librelist.com/browser//breathe/2011/8/6/fwd-guidance- for-usage-breathe-with-existing-doxygen-set-up-on-a-large-project / # cab3f36b1e4bb2294e2507acad71775f ),

It is ironic that Doxygen is installed on the read-the-docs server, but after the struggle, I could not find a workaround to skip its Sphinx or Mkdocs.

+8
doxygen read-the-docs
source share
1 answer

I tried the following solution for using Doxygen in Read The Docs and it seems to work:

  • install an empty sphinx project (see the official sphinx document),
  • in sphinx conf.py add a command to create documentation for oxygen,
  • use the conf.py html_extra_path configuration to overwrite the generated doxygen documentation on the generated sphinx documentation.

I tested this with the following source tree:

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

Some explanation:

  • in my setup doxygen creates its documentation in "doc / build / html",
  • ReadTheDocs runs its commands in the directory where it finds the conf.py file.

What to do:

  • add the following lines to conf.py to generate doxygen docs:

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

  • Update the conf.py html_extra_path directive to:

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

In this configuration, ReadTheDocs must correctly create and store the Doxygen html documentation.

TODO:

  • other documentation formats, for example: pdf.
+6
source share

More articles:


All Articles