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.

• Doxyrest 1.1.1-a
• Doxyrest 1.1.0

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

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

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:

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.

Follow the links below for additional information:

• Doxyrest Manual
• Doxyrest Build Guide