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 templating 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. It's also possible to replace Doxygen at the first stage with another compatible XML generator and use the same pipeline for languages other than C/C++.

Latest Release

Doxyrest 2.1.3

New in Doxyrest 2

• Multiple sets of language-specific frames:

  • C-family
  • Lua
  • CMake

• Subgroups:

  Often times a bunch of methods relate so closely to one another that they simply do not deserve a dedicated documentation block for each and every one. Merge them together into a subgroup and let them share the same documentation block!

• Footnotes:

  Footnotes are essential for a good documentation system. Alas, Doxygen doesn't provide any support for that at all. But there is a workaround now!

• Target highlights:

  Often times you click a link, and you jump somewhere, but... where exactly?! With Doxyrest it's not an issue -- both documented and undocumented items get properly highlighted when jumped to!

• Configurable declaration style:

  Opening braces	class MyClass { ... }	vs	class MyClass { ... }
  Type specifiers	static bool foo();	vs	static bool bar();
  Parameter lists	void foo(int a, int b);	vs	void bar( int a, int b );

... and many other settings. Or -- create a completely custom style by editing frames!

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

Replace Doxygen with your own generator of Doxygen-compatible XML database and apply the same pipeline for documenting APIs in other languages:

Lua libraries

Doxyrest Lua API	sphinx_rtd_theme
Doxyrest Frame Settings	sphinx_rtd_theme

The above manuals were generated from Doxy-comments inside .lua files by using LuaDoxyXML instead of Doxygen at the first stage of the pipeline.

Jancy libraries

Jancy Standard Library	sphinx_rtd_theme
IO Ninja Jancy API	sphinx_rtd_theme

The above manuals were generated from Doxy-comments inside .jnc files by using the official Jancy compiler instead of Doxygen at the first stage of the pipeline.

To reiterate, the strongest point of the Doxyrest approach is that it's modular and 100% customizable. You can replace the XML-generator to support new languages; you can change Sphinx themes or CSS styles to tweak the visual appearance (fonts, colors, page layout, etc), and if that doesn't cut it, you can modify the Lua frames for more drastic effects -- from tweaking the declaration coding style to changing the whole structure of documentation.

Quick HOWTO

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

1. Get Tool Binaries

You can 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.

Sphinx Version

Note that Doxyrest requires Sphinx v1.7.0 or above. If the Sphinx version from the official repos of your Linux distro is below that, please use pip to install a newer one.

2. Prepare Configuration Files

2.1. Doxyfile for Doxygen

Adjust the following settings in your Doxygen configuration file Doxyfile:

# Obviously, we do need XML:

GENERATE_XML = YES

# You may also want to turn the generation of HTML off:
# GENERATE_HTML = NO

# Next, choose the location of the resulting XML database:

XML_OUTPUT = xml-dir

# Program listing vastly increases the size of XML so it's recommended
# to turning it OFF:

XML_PROGRAMLISTING = NO

# The next one is essential! Sphinx uses lowercase reference IDs,
# so Doxygen can't use mixed-case IDs:

CASE_SENSE_NAMES = NO

# The next one is important for C++ projects -- otherwise Doxygen
# may generate lots of bogus links to template arguments:

HIDE_UNDOC_RELATIONS = YES

# The last one is 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:

EXTRACT_ALL = YES

2.2. doxyrest-config.lua for Doxyrest

Copy the default configuration file from doxyrest-frame-dir/doxyrest-config.lua and adjust the necessary settings. Here's what may need adjustment for existing Doxygen-based C/C++ projects:

-- Specify input and output paths:

OUTPUT_FILE = "rst-dir/index.rst"
INPUT_FILE = "xml-dir/index.xml"
FRAME_FILE = "index.rst.in"
FRAME_DIR_LIST = { "doxyrest-frame-dir/cfamily", "doxyrest-frame-dir/common" }

-- Usually, Doxygen-based documentation has a main page (created with
-- the \mainpage directive). If that's the case, force-include
-- the contents of 'page_index.rst' into 'index.rst':

INTRO_FILE = "page_index.rst"

-- If your documentation uses \verbatim directives for code snippets
-- you can convert those to reStructuredText C++ code-blocks:

VERBATIM_TO_CODE_BLOCK = "cpp"

-- Asterisks, pipes and trailing underscores have special meaning in
-- reStructuredText. If they appear in Doxy-comments anywhere except
-- for code-blocks, they must be escaped:

ESCAPE_ASTERISKS = true
ESCAPE_PIPES = true
ESCAPE_TRAILING_UNDERSCORES = true

For detailed documentation on all settings please read the Frame Settings Reference.

2.3. conf.py for Sphinx

Finally, prepare a Sphinx configuration file conf.py. A good approach would be generating one using sphinx-quickstart and then adding the following:

# Specify the path to Doxyrest extensions for Sphinx:

sys.path.insert(1, os.path.abspath('doxyrest-sphinx-dir'))

# Add Doxyrest extensions ``doxyrest`` and ``cpplexer``:

extensions += ['doxyrest', 'cpplexer']

# If you used INTRO_FILE in 'doxyrest-config.lua' to force-include it
# into 'index.rst', exclude it from the Sphinx input (otherwise, there
# will be build warnings):

exclude_patterns += ['page_index.rst']

Standard install locations for the Doxyrest Sphinx extensions (doxyrest and cpplexer):

Windows	%DOXYREST_DIR%\sphinx
Linux, macOS	$DOXYREST_DIR/share/doxyrest/sphinx

If in doubt, please navigate to the Doxyrest Sphinx extension directory and make sure doxyrest.py and cpplexer.py are there.

3. Run The Doxyrest Pipeline

After the configuration files are ready, it's time to build:

# stage 1: generate Doxygen XML

$ doxygen Doxyfile

# stage 2: generate reStructuredText

$ doxyrest -c doxyrest-config.lua

# stage 3: generate HTML

$ sphinx-build -b html rst-dir html-dir

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

4. Play With The Styles (optional)

Alright, you were able to generate HTML documentation, but you would like to tweak some styles (colors, fonts, margins, etc). With Sphinx, you can easily adjust both the theme and CSS stylesheets. Doxyrest extensions for Sphinx also allow you setting the tab-width (tab-width being hardcoded to 8 is a longtime issue with Sphinx).

To do all that, edit your conf.py:

# Choose a Sphinx theme:

html_theme = 'sphinx_rtd_theme'

# Prepare a folder ./static/ with all the .css files you want to replace, e.g.
#     ./static/pygments.css
#     ./static/css/theme.css
#     ...
# Then ask Sphinx to write it over the standard '_static' folder:

html_static_path = ['static/']

# Specify the size of tab indentation:

doxyrest_tab_width = 2

If you use a theme other than sphinxdoc or sphinx_rtd_theme (natively supported by Doxyrest), make sure your stylesheets properly define the following Doxyrest-specific .css classes:

pre.doxyrest-overview-code-block {
        ...
}

pre.doxyrest-overview-inherited-code-block {
        ...
}

pre.doxyrest-title-code-block {
        ...
}

.doxyrest-target-highlight {
        ...
}

Use doxyrest-sphinx-dir/css/doxyrest-sphinxdoc.css and doxyrest-sphinx-dir/css/doxyrest-sphinx_rtd_theme.css as examples for how to do that.

Documentation

Follow the links below for additional information:

• Doxyrest Manual

• Doxyrest Build Guide

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