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.
Check out the results of Doxyrest' handiwork in application to a few open-source projects:
|Apache Portable Runtime||sphinx_rtd_theme||sphinxdoc||vs||original|
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:
|Jancy Standard Library||sphinx_rtd_theme|
|IO Ninja Jancy API||sphinx_rtd_theme|
Here is a list of steps required to apply Doxyrest to existing Doxygen-based projects:
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.
Adjust the following settings in your Doxygen configuration file
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
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
sys.path.insert(1, os.path.abspath('$DOXYREST_SPHINX_DIR')) extensions += ['doxyrest', 'cpplexer']
Usually, Doxygen-based documentation has a main page (created with the
\mainpagedirective). If that's the case, add this to avoid build warnings (this page will be force-included):
exclude_patterns += ['page_index.rst']
Run Doxygen to generate an XML database. The exact way of doing so depends on the project; it may look like:
cmake --build . --target doc
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
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
\verbatimDoxygen-directives, you can convert those to reStructuredText code blocks by appending:
For some Doxygen-based project it also may help to add:
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.
Finally, run Sphinx to build HTML pages:
sphinx-build -b html $TMP_RST_DIR $OUTPUT_HTML_DIR
$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: