A compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen and produces reStructuredText for the Python documentation generator Sphinx.
Switch branches/tags
Nothing to show
Clone or download
vovkos [doxyrest] use io::concatFilePath instead of explicit string concaten…
…ation

previously, doxyrest attempted to access the root dir if -o was not specified
Latest commit fd01477 Nov 22, 2018

README.rst

Doxyrest

https://travis-ci.org/vovkos/doxyrest.svg?branch=master https://ci.appveyor.com/api/projects/status/n41qiwei26t7o0pq?svg=true

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.

/doc/manual/images/doxyrest-pipeline.png

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

Downloads

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: