.. ............................................................................. .. .. This file is part of the Doxyrest toolkit. .. .. Doxyrest is distributed under the MIT license. .. For details see accompanying license.txt file, .. the public copy of which is also available at: .. http://tibbo.com/downloads/archive/doxyrest/license.txt .. .. .............................................................................

Doxyrest

.. image:: https://github.com/vovkos/doxyrest/actions/workflows/ci.yml/badge.svg :target: https://github.com/vovkos/doxyrest/actions/workflows/ci.yml .. image:: https://codecov.io/gh/vovkos/doxyrest/branch/master/graph/badge.svg :target: https://codecov.io/gh/vovkos/doxyrest .. image:: https://img.shields.io/badge/[email protected] :align: right :target: http://jancy.org/donate.html?donate=doxyrest

Abstract

Doxyrest is a compiler from Doxygen XML to reStructuredText -- hence, the name. It parses XML databases generated by Doxygen <http://www.stack.nl/~dimitri/doxygen/>, feeds those to the Lua-based string templating engine and produces reStructuredText <http://docutils.sourceforge.net/rst.html> suitable for being passed further on to the Python documentation generator Sphinx <http://www.sphinx-doc.org>__.

.. image:: /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. 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 <https://github.com/vovkos/doxyrest/releases/tag/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 <https://vovkos.github.io/doxyrest/manual/subgroups.html>__ 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 <https://vovkos.github.io/doxyrest/manual/footnotes.html>__ 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:

  .. list-table::

    *	-	`Opening braces <https://vovkos.github.io/doxyrest/manual/group_frame-config.html#doxid-variable-pre-body-nl>`__
  
    	-	.. code-block:: cpp
  
    			class MyClass {
    				...
    			}
  
    	- vs
  
    	-	.. code-block:: cpp
  
    			class MyClass
    			{
    				...
    			}
  
    *	-	`Type specifiers <https://vovkos.github.io/doxyrest/manual/group_frame-config.html#doxid-variable-ml-specifier-modifier-list>`__
  
    	-	.. code-block:: cpp
  
    			static bool foo();
  
    	- vs
  
    	-	.. code-block:: cpp
  
    			static
    			bool
    			bar();
  
    *	-	`Parameter lists <https://vovkos.github.io/doxyrest/manual/group_frame-config.html#doxid-variable-ml-param-list-count-threshold>`__
  
    	-	.. code-block:: cpp
  
    			void foo(int a, int b);
  
    	- vs
  
    	-	.. code-block:: cpp
  
    			void bar(
    				int a,
    				int b
    			);
  

... and many other settings <https://vovkos.github.io/doxyrest/manual/group_frame-config.html>__. 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

.. list-table::

	*	- LibUSB
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/samples/libusb>`__
		- `sphinxdoc <https://vovkos.github.io/doxyrest/samples/libusb-sphinxdoc>`__
		- vs
		- `original <http://libusb.sourceforge.net/api-1.0>`__

	*	- LibSSH
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/samples/libssh>`__
		- `sphinxdoc <https://vovkos.github.io/doxyrest/samples/libssh-sphinxdoc>`__
		- vs
		- `original <http://api.libssh.org/stable>`__

	*	- ALSA Library
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/samples/alsa>`__
		- `sphinxdoc <https://vovkos.github.io/doxyrest/samples/alsa-sphinxdoc>`__
		- vs
		- `original <http://www.alsa-project.org/alsa-doc/alsa-lib>`__

	*	- Apache Portable Runtime
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/samples/apr>`__
		- `sphinxdoc <https://vovkos.github.io/doxyrest/samples/apr-sphinxdoc>`__
		- vs
		- `original <https://apr.apache.org/docs/apr/1.5>`_

C++ libraries

.. list-table::

*	- OpenCV
	- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest-showcase/opencv/sphinx_rtd_theme>`__
	- `sphinxdoc <https://vovkos.github.io/doxyrest-showcase/opencv/sphinxdoc>`__
	- vs
	- `original <http://docs.opencv.org/trunk>`__

*	- POCO Libraries
	- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest-showcase/poco/sphinx_rtd_theme>`__
	- `sphinxdoc <https://vovkos.github.io/doxyrest-showcase/poco/sphinxdoc>`__
	- vs
	- `original <https://pocoproject.org/docs>`__

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

.. list-table::

* 	- AXL
	- `sphinx_rtd_theme <https://vovkos.github.io/axl/manual/global.html>`__

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

Lua libraries

.. list-table::

	*	- Doxyrest Lua API
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/manual/group_api.html>`__

	*	- Doxyrest Frame Settings
		- `sphinx_rtd_theme <https://vovkos.github.io/doxyrest/manual/group_frame-config.html>`__

The above manuals were generated from Doxy-comments inside ``.lua`` files by using `LuaDoxyXML <https://github.com/vovkos/luadoxyxml>`__ instead of Doxygen at the first stage of the pipeline.

Jancy libraries

.. list-table::

*	- Jancy Standard Library
	- `sphinx_rtd_theme <https://vovkos.github.io/jancy/stdlib>`__

*	- IO Ninja Jancy API
	- `sphinx_rtd_theme <http://ioninja.com/doc/api>`__

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 <https://github.com/vovkos/doxyrest/releases/latest>`__ or build Doxyrest yourself. If you've chosen the latter, it's recommended to build using the auxillary bundle repo `doxyrest_b <https://github.com/vovkos/doxyrest_b>`__. Refer to the `Doxyrest Build Guide <https://vovkos.github.io/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:

.. code-block:: bash

# 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:

.. code-block:: lua

-- 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 <https://vovkos.github.io/doxyrest/manual/group_frame-config.html>__.

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:

.. code-block:: python

# 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):

.. list-table::

*	- 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:

.. code-block:: bash

		# 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:

.. code-block:: python

# 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:

.. code-block:: css

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 <https://vovkos.github.io/doxyrest/manual>__

• Doxyrest Build Guide <https://vovkos.github.io/doxyrest/build-guide>__

  Of course, you can also follow the build logs on Travis CI <https://travis-ci.org/vovkos/doxyrest>__ or AppVeyor CI <https://ci.appveyor.com/project/vovkos/doxyrest>__ -- always a great way to reproduce the build steps.