Doxyrest

Abstract

Doxyrest is a compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen, feeds those to the Lua-based string template engine and produces reStructuredText suitable for being passed further on to the Python documentation generator Sphinx.

This elaborate pipeline allows building beautiful documentation for C/C++ APIs with little-to-no changes in the existing in-source Doxygen comments.

Downloads

• Doxyrest 1.1.1-a
• Doxyrest 1.1.0

Samples

Check out the results of Doxyrest' handiwork in application to a few open-source projects:

C libraries

LibUSB	sphinx_rtd_theme	sphinxdoc	vs	original
LibSSH	sphinx_rtd_theme	sphinxdoc	vs	original
ALSA Library	sphinx_rtd_theme	sphinxdoc	vs	original
Apache Portable Runtime	sphinx_rtd_theme	sphinxdoc	vs	original

C++ libraries

OpenCV	sphinx_rtd_theme	sphinxdoc	vs	original
POCO Libraries	sphinx_rtd_theme	sphinxdoc	vs	original

Doxyrest generates a decent overview even if a project has no Doxygen documentation comments at all:

AXL	sphinx_rtd_theme

But the best part about the Doxyrest approach is that it's modular and 100% customizable. You can play with Sphinx themes to change visual appearance (fonts, colors, page layout, etc). Or you can modify Lua frames for more drastic effects -- from tweaking the declaration coding style to changing the whole structure of documentation!

You can even replace Doxygen with your own generator of Doxygen-style XML database and then apply the same pipeline for documenting APIs in other languages:

Jancy libraries

Jancy Standard Library	sphinx_rtd_theme
IO Ninja Jancy API	sphinx_rtd_theme

Quick HOWTO

Here is a list of steps required to apply Doxyrest to existing Doxygen-based projects:

1. Get Doxyrest binaries -- either download precompiled packages from the latest GitHub release or build Doxyrest yourself. If you've chosen the latter, it's recommended to build using the auxillary bundle repo doxyrest_b. Refer to the Doxyrest Build Guide for more details.

2. Adjust the following settings in your Doxygen configuration file Doxyfile:

   GENERATE_XML         = YES  # self-explanatory
   
   CASE_SENSE_NAMES     = NO   # essential! Sphinx uses lowercase reference IDs,
                               # so Doxygen can't use mixed-case IDs
   
   HIDE_UNDOC_RELATIONS = YES  # important for C++ projects -- otherwise Doxygen
                               # may generate bogus links to template arguments
   
   XML_PROGRAMLISTING   = NO   # not essential, but highly recommended -- enabling
                               # program listing vastly increases the size of XML
   
   EXTRACT_ALL          = YES  # not essential, but recommended if your project
                               # sets AUTOLINK_SUPPORT to ON (like most projects
                               # do) -- otherwise auto-generated links may point
                               # to discarded items

3. Prepare Sphinx configuration file conf.py -- either take an existing one and fine tune it to your liking, or generate a new one with sphinx-quickstart. Now add Doxyrest extensions doxyrest and cpplexer:

   sys.path.insert(1, os.path.abspath('$DOXYREST_SPHINX_DIR'))
   extensions += ['doxyrest', 'cpplexer']

   Usually, Doxygen-based documentation has a main page (created with the \mainpage directive). If that's the case, add this to avoid build warnings (this page will be force-included):

   exclude_patterns += ['page_index.rst']

4. Run Doxygen to generate an XML database. The exact way of doing so depends on the project; it may look like:

   make doc
   

   or:

   cmake --build . --target doc
   

   or simply:

   doxygen
   

5. Run Doxyrest to build reStructuredText documentation from the XML database obtained on the previous step:

   doxyrest $DOXYGEN_XML_DIR/index.xml -o $TMP_RST_DIR/index.rst -F $DOXYREST_FRAME_DIR -f c_index.rst.in
   

   If your project has a main page (see above), append the following to the command line to force-include the contents of page_index.rst into index.rst:

   -D g_introFile=page_index.rst
   

   Otherwise, you may want to specify the title for index.rst (default title is "My Project Documentation"):

   -D "g_indexTitle=Title Goes Here"
   

   If your documentation uses \verbatim Doxygen-directives, you can convert those to reStructuredText code blocks by appending:

   -D g_verbatimToCodeBlock=cpp
   

   For some Doxygen-based project it also may help to add:

   -D g_escapeAsterisks
   

   This only makes a difference if asterisks characters * (which have special meaning in reStriucturedText) are used in regular paragraph text of your documentation. Asterisks in code snippets will work just fine even without this switch.

6. Finally, run Sphinx to build HTML pages:

   sphinx-build -b html $TMP_RST_DIR $OUTPUT_HTML_DIR
   

Now open $OUTPUT_HTML_DIR/index.html and enjoy the new awesome look of your documentation!

Of course, you can also follow the build logs on Travis CI -- always a great way to reproduce build steps.

Documentation

Follow the links below for additional information:

• Doxyrest Manual
• Doxyrest Build Guide