Ubuntu Manpages

doxysphinx

Doxysphinx 3.3.12

In this guide we'll walk you through setting up doxysphinx for your doxygen and sphinx project.

NOTE:

This guide expects that you want to integrate doxysphinx in your own project. If you just want to testdrive it and see how things working we recommend to clone the repo, fire up vscode and enter the devcontainer.


Please be sure to fulfill the following prerequisites.

TIP:

You can also look at the source code of this project for reference - especially the [devcontainer]({{ code }}/.devcontainer) has everything set up already.


You need a project upfront with:

  • doxygen installed and configured.
  • sphinx installed and configured.

You should already have installed python, doxygen and sphinx. If yes - great! If not please install them:

  • Python 3.7+
  • Doxygen
  • Sphinx

Doxysphinx is distributed as pypi package.

Install it with:

pip install doxysphinx


NOTE:

If you have trouble installing/running the package, please look into our FAQ (section I.1) where we describe some alternatives.


Next you have to prepare your doxygen configuration file (doxyfile) to have compatible settings with doxysphinx.

The following settings are mandatory and will be checked by a validator if you use your doxyfile as input for doxysphinx (if you use the doxygen html output directory instead validation will be skipped):

these settings are absolutely needed (Doxysphinx will throw detailed errors in case of incorrect ones):

OUTPUT_DIRECTORY       = <anywhere_below_you_sphinx_documentation_source_root!!!> # see note below
GENERATE_TREEVIEW      = NO   # Deactivate doxygens own treeview (as it doesn't look right)
DISABLE_INDEX          = NO   # Menu data is crucial for our TOC generation so it mustn't be disabled
GENERATE_HTML          = YES  # Keep sure that you generate HTML which needed for doxysphinx
CREATE_SUBDIRS         = NO   # NO is the default value and it should be no because doxysphinx can't handle subdirs right now.


NOTE:

Why the heck the doxygen output_dir needs to live inside the sphinx docs root?

Right now for each doxygen html output file a rst file is generated with the same name/path but different extension. We did this because sphinx will then automatically generate the html files for the rsts at the correct relative location - and no doxygen-documentation-internal links will break - they just stay the same. However this has the implication that the doxygen html output has to live inside/somewhere below the sphinx source directory (we recommend using something like docs/doxygen/YOUR_LIBRARY_NAME/). If that isn't the case for you doxysphinx will complain and exit.

But I don't want my docs dir to get polluted with generated code!

Yes, we don't like that either, but one of our design goals was performance and scanning htmls and correcting links is just one additional step that takes time and makes things more complicated.

Our recommendation is to just gitignore the generated doxygen docs dir. If you cannot live with it you could take a look at the alternatives.



these settings are optional but strongly recommended (you will be notified in case of some value deviations):

SEARCHENGINE           = NO   # deactivate search engine (as sphinx has it's own search)
GENERATE_TAGFILE       = <OUTPUT_DIRECTORY>/<HTML_OUTPUT>/tagfile.xml  # generate a tag file
                              # this could be stored anywhere, however we recommend to put it into the
                              # documentation output folder which is the value of the OUTPUT_DIRECTORY variable
                              # + the value of the HTML_OUTPUT variable (your have to expand it for yourself
                              # because doxygen has no mechanism to reference config settings that were defined
                              # beforehand.
                              # The tagfile is also needed for the doxylink extension
DOT_IMAGE_FORMAT       = svg  # generates nicer svg images
DOT_TRANSPARENT        = YES  # generate transparent images
INTERACTIVE_SVG        = YES  # to be able to scroll and zoom into big images
# if you want to use aliases instead of markdown fences for commenting (see syntax guide) you have to add
# something like this (which doesn't hurt either):
ALIASES                = "rst=\verbatim embed:rst:leading-asterisk" \
                         endrst=\endverbatim  # This allows you to use rst blocks inside doxygen comments with @rst and @endrst


TIP:

Doxygen awesome is a stylesheet that makes doxygen documentation look beautiful. We strongly recommend using it because then the doxygen docs would fit far better with any sphinx theme. Just download/clone the doxygen awesome stylesheet and then add it to your doxygen config: 

HTML_EXTRA_STYLESHEET = YOUR_DOXYGEN_AWESOME_PATH/doxygen-awesome.css




Now it's time to run doxysphinx.

You can either do it manually or integrate it in your makefile, cmake, whatever...

NOTE:

Keep sure that you first run doxygen.


The doxysphinx cli/executable has the following commands/options.

Show command and usage information. This will also show the most up to date documentation as this guide will only handle the basics:

doxysphinx --help
doxysphinx <command> --help


Build the sphinx rst documents out of the doxygen htmls.

doxysphinx build <SPHINX_SOURCE> <SPHINX_OUTPUT> <INPUT(S)> <--doxygen_exe> <--doxygen_cwd>


Arguments:

Variable Descriptions
SPHINX_SOURCE The root of your sphinx source/input directory tree.Often this is the same directory your conf.py is in.
SPHINX_OUTPUT The root of you sphinx output directory tree - where sphinx puts the generated html files to. This should be the directory where sphinx put's it's main index.html to.
INPUT(S) One or many inputs where each input could be either...a doxygen configuration file (doxyfile). This is recommended for "beginners" because it will also check the config for doxysphinx compatibility.an output path where the generated doxygen documentation resides. This is more like an "expert"-mode which is especially useful when integrating doxysphinx with buildsystems like cmake etc. which are dynamically generating doxygen configs.
--doxygen_exe The name/path of the doxygen executable. If nothing is entered, the default value is "doxygen". (OPTIONAL)
--doxygen_cwd The directory where doxygen is executed. The default value is the current working directory. (OPTIONAL)

Replace the following arguments:

WARNING:

Please note that sphinx has slightly different output directories depending on the arguments:
  • the html output will be put to OUTPUT_DIR so doxysphinx's SPHINX_OUTPUT should be OUTPUT_DIR.
  • the html output will be put to OUTPUT_DIR/html so doxysphinx's SPHINX_OUTPUT should be OUTPUT_DIR/html.



If you want to remove the files doxysphinx generated please use the clean command:

doxysphinx clean <SPHINX_SOURCE> <SPHINX_OUTPUT> <INPUT(S)>


Add/extend the following targets in your makefile:

clean:
  @doxysphinx clean <SPHINX_SOURCE> <SPHINX_OUTPUT> <INPUT(S)>
doxysphinx:
  @doxysphinx build <SPHINX_SOURCE> <SPHINX_OUTPUT> <INPUT(S)>


Now you just need to call the doxysphinx target right after your doxygen is running.

Finally we can start using rst snippets in doxygen comments.

Open some C/C++ file and add a comment like this to one of your functions/methods/whatever:

/// @brief Creates a new instance of the Car.
///
/// @param engine - the engine to use for this Car.
/// @param color - the color of this Car.
///
/// @rst
/// .. hint::
///    Rst text can also be included after the params.
///
/// @endrst
Car(Engine& engine, Color& color) {};


Note the @rst and @endrst tags. Inside these tags you can write any rst code.

See also the Syntax Guide for a complete documentation on how to comment for doxysphinx.

Now run doxygen, doxysphinx and sphinx and look at the generated documentation. You should see something like this: [image: Demo of final generated html] [image]

🎉 Congratulations you've completed the quickstart.

  • To link from sphinx documentation directly to doxygen documented symbols -> see our setting up doxylink guide.(Strongly recommended.)

  • To get to know the doxysphinx comment syntax -> see our syntax guide.
  • Maybe you want to know more about the inner workings? -> head over to the reference section.
  • Or look at some examples? -> linking to doxygen.
  • Or do you want to contribute and bring doxysphinx to the next level? Read the contributors guide and the Developer Quickstart.

Or just start documenting 😀.

Here you can see how you have to write your comments in doxygen for doxysphinx to pick them up.

For creating blocks of restructured text content in C++ documentation comments that will be rendered by Sphinx.

TLDR; Recommended Syntax

  • if you want to use the shortest possible syntax use Markdown Fences with directive autodetection.
  • if you're coming from breathe and already have your code commented with breathe markers or if you want to have maximum compatibility: use Doxygen aliases.

However if you experience any problems with doxygen parsing etc. you might try one of the other options described in Supported rst block delimiters in doxygen comments.

For doxysphinx to be able to identify a rst block we only need to have some kind of "verbatim block" in html output and a special marker at the beginning of the content.

The marker can be one of these:

  • {rst} -> our (doxysphinx) own marker
  • embed:rst
  • embed:rst:leading-asterisk
  • embed:rst:leading-slashes -> breathe compatibility markers

After any marker there has to be a new line (content can start at next line).

As chances are quite big that you just want to use a sphinx directive we've also got an autodetection feature: if the "verbatim content" starts with a directive you can leave out the markers (in that case the directive syntax is the marker), for example...

/// ```
/// .. directive:: title
///    DIRECTIVE CONTENT
/// ```


...will also be identified by doxysphinx as a rst block (and processed).

Technically doxysphinx searches for <pre>- or <div class="fragment">-elements in doxygen html output because these are the elements it uses for verbatim code block content. There are several ways in doxygen to create these kind of elements:

You can use the markdown code fences syntax as follows (you need to have markdown enabled in doxygen to use it):

/// ...
///
/// ```
/// {rst}
/// enter your rst content,
/// like directives, free text rst content,
/// etc...
/// ```
///
/// ...


WARNING:

In markdown it's typical to have a language identifier right behind the beginning "fence". Something like ```cpp for example. However the doxygen markdown parser will swallow anything behind the delimiters (which means we couldn't make use of information there). So please do not fall into the trap trying to start a rst block with e.g. ```{rst}. The {rst} marker (or any content used by doxysphinx) has to be on the next line. (This is only true if you use markdown code fences - not for the other options below).


\verbatim special command

You can use the verbatim special command in doxygen to create a pre-element:

/// ...
///
/// \verbatim {rst}
/// enter your rst content,
/// like directives, free text rst content,
/// etc...
/// \endverbatim
///
/// ...


<pre>-html-element

As you can also use html in doxygen you can use the html <pre>-element directly:

/// ...
///
/// <pre> {rst}
/// enter your rst content,
/// like directives, free text rst content,
/// etc...
/// </pre>
///
/// ...


As another shortcut you can also use doxygen aliases to create your own rst-block delimiters:

ALIAS       =  "rst=\verbatim embed:rst"
ALIAS       += "endrst=\endverbatim"


And then use the alias like this:

/// ...
///
/// \rst
/// enter your rst content,
/// like directives, free text rst content,
/// etc...
/// \endrst
///
/// ...


More examples

can be found in our demo documentation here.

For creating inline restructured text content in C++ documentation comments that will be rendered by Sphinx.

TLDR; Recommended Syntax

Use the following syntax in your C++ documentation comments to use a sphinx role in-line (note that you have to replace the backticks usually used in rst/sphinx with quotes):

/// lorem ipsum, `:role:"content of the role"` dolor sit...


e.g.

/// Here you can find the `:doc:"Main Documentation <index>"`. Please read it carefully.


This will work only if markdown support is activated in doxygen (highly recommended).

Furthermore, please note that you can only use sphinx roles and domains in the inline syntax for now (reasoning see below).

See below in the methods documentation for other options if you have markdown support disabled.

Skip this section if you're not interested in the technical details...

Inline rst is a major problem because of the following:

1.
Paragraphs all over the place

Doxygen uses paragraphs (<p>-html-tags) for it's content. Paragraph tags cannot have other block-level tags inside them (even no other paragraph tags). The browsers (chromium-based ones, Firefox etc.) are quite aggressive in fixing bad nestings here (just to be able to display a page). So e.g. if a nested <p>-tag is noticed the browsers will close the outer <p>-tag right before the inner <p>-tag. This will linearize the <p>-tags and the page could be rendered.

When we now split our content for mixed rst content as described in :doc:"/docs/inner_workings" we end up having raw-html blocks and inline-rst blocks (and also other rst blocks but that doesn't matter here). Sphinx will automagically put <p>-tags around the inline-rst-block - it's doing that around all pure text based content and we cannot change that.

Most of the time this results in an html structure with nested <p>-tags which will be "fixed" by the browsers on loading/rendering of the html page. Why is this a problem? because we cannot style (in a css sense) away the blockiness if we have only sibling <p>-tags. But we have to for the content to appear "in-line". Also we cannot fix the final html structure because we're too early in the process. We can only create rsts which will then be picked up by sphinx to create the final html.

2.
Doxygen interpretation/preprocessing

The main use case for inline rst are sphinx roles which are normally (in rst) written in a form like:

:role_name:`role_content`


but doxygens internal markdown support will parse the backticks as markdown inline code block and renders code-tags all over the place then.


the following solutions/hacks have been applied to overcome the problems:

1.
Html-Element-Transformation

If we encounter a sphinx role in doxysphinx during original doxygen html parsing we change it's parent html tag from <p>-tag to <div>-tag (because divs can have nested content). We also add a css class which we use to style the "blockiness" away (display:inline). The technical implementation is has more complexity - if you're interested just look into the code.

2.
Adjusted Syntax for using inline rst and special parsing

Doxysphinx scans the html for <code>-tags but that's not enough. For doxysphinx to consider a <code>-tag as inline sphinx snippet it has to be in the format <code>:role:`content`</code> - we validate the syntax here and if it doesn't match we ignore it. The implication is that you cannot use anything other than roles/domains for inline rst. In practice this means that you cannot use rst's external link syntax and references for now, which is however so cryptic that we're quite sure that you would rather consider using doxygens link command or just a markdown link.

Furthermore backticks are also markdown's verbatim inline delimiters and therefore can only be used when escaped (and even then they create problems with doxygen's way of parsing). Therefore we're also supporting (and are recommending) quotes (") and ticks (') as role content delimiters. So we relaxed the sphinx syntax a little bit here to work better in doxygen comments.


Technically doxysphinx searches for <pre>- or <div class="fragment">-elements in doxygen html output because these are the elements it uses for verbatim code block content. There are several ways in doxygen to create these kind of elements:

You can use markdown inline code syntax:

/// A markdown inline statement with quotes like this - `:doc:"Main Documentation <index>"` - will work.


WARNING:

The role content delimiter has to be a quote ("). Ticks and escaped backticks won't work with markdown inline code syntax because of doxygens parser.


<code>-html-element

You can also use a html <code>-element:

/// A html code element with quotes like this - <code>:doc:"Main Documentation <index>"</code> - will work.
///
/// A html code element with ticks like this - <code>:doc:'Main Documentation <index>'</code> - will work.
///
/// A html code element with escaped backticks like this - <code>:doc:\`Main Documentation <index>\`</code> - will work.


<tt>-html-element

You can also use a html <tt>-element:

/// A html tt element with quotes like this - <tt>:doc:"Main Documentation <index>"</tt> - will work.
///
/// A html tt element with ticks like this - <tt>:doc:'Main Documentation <index>'</tt> - will work.
///
/// A html tt element with escaped backticks like this - <tt>:doc:\`Main Documentation <index>\`</tt> - will work.


More examples

can be found in our demo documentation here.

We're supporting the following Doxygen comment styles (see also Doxygen: Comment Blocks for C-Style Languages).

/// @brief brings the unicorns back
///
/// It does that with an extraordinary special top secret device of extraterrestrial origin.
void bring_the_unicorns_back();



/**
 * @brief brings the unicorns back
 *
 * It does that with an extraordinary special top secret device of extraterrestrial origin.
 */
void bring_the_unicorns_back();


or

/**
  @brief brings the unicorns back
  It does that with an extraordinary special top secret device of extraterrestrial origin.
 */
void bring_the_unicorns_back();



/*!
 * @brief brings the unicorns back
 *
 * It does that with an extraordinary special top secret device of extraterrestrial origin.
 */
void bring_the_unicorns_back();


or

/*!
  @brief brings the unicorns back
  It does that with an extraordinary special top secret device of extraterrestrial origin.
 */
void bring_the_unicorns_back();



//! @brief brings the unicorns back
//!
//! It does that with an extraordinary special top secret device of extraterrestrial origin.
void bring_the_unicorns_back();


If doxysphinx doesn't fit your needs maybe there are some other open source tools which might be a better fit:

  • Breathe
  • Exhale
  • Doxyrest
  • wurfapi
  • sphinxcontrib-autodoc_doxygen

These seem abandoned:

  • gasp
  • doxygraph

The tools Breathe and Exhale needs special mention, as doxysphinx was invented in a large C++ project (> 11,000 C++ files) where we started out with these two tools. With the large project size, Exhale did not perform too well and Breathe did not quite support all C++ and Doxygen features that C++ developers expected. Doxysphinx was invented to overcome these limitations.

Breathe is useful for smaller C++ projects when parts of C++ Doxygen documentation needs to be integrated into the Sphinx documentation using Breathe directives. When the complete C++ Doxygen documentation needs to be integrated into Sphinx, the following options are available:

  • breathe.apidoc
  • Exhale

Doxysphinx outperforms the two options w.r.t to speed and features, as it simply reuses Doxygen output.

Also note that Breathe and Doxysphinx can co-exist in the same project.

Doxysphinx doesn't have many runtime dependencies, however especially click (cli tool) might introduce these problems (as it's very widely used).

You have several options:

First time setup:

# create a new virtual environment in your project root
python3 -m venv .venv-doxysphinx
# install doxysphinx into new virtual environment
.venv-doxysphinx/bin/pip3 installdoxysphinx


Usage:

# you then have 2 options to call doxysphinx:
# Option A): call doxysphinx inside virtualenv
source .venv-doxysphinx/bin/activate
doxysphinx
# Option B): call doxysphinx directly without activating venv
.venv-doxysphinx/bin/doxysphinx


Head over to the [github releases]({{ repo }}/releases) section and download the pex package. This is a self contained executable which should work if you have a compatible python installed.

You can try to override the CSS styles for your theme. If you take a look into our repo's [docs/_static]({{ code }}/docs/_static/) folder you can see 2 custom theme-override-css files. The mechanism to load the correct one is defined in the [conf.py]({{ code }}/conf.py) (html_css_files setting).

However in general you just need to put your css into a path configured in html_static_path and then reference it in html_css_files and it will get loaded.

We use Lunacy at present as graphics editor to just get svg files in the end. At present Lunacy is free for personal and commercial use.

The sketch format can also be used with Sketch and other tools like Figma are also able to at least import it.

However in the end any svg editor will do. If you contribute, contribute svgs. If you're happening to use another editing tool that has another native format you can just check the original sources in.

If you want to stay full open source Inkscape is a very good option to just have a good svg editor.

In descending order of preference:

  • svg
  • png

If these formats cuts information from the original file please also consider providing the original.

TIP:

As you know from Getting Started-guide your doxygen documentation has to be created in the SPHINX_SOURCE directory tree.

We recommend to put it under a special doxygen folder, e.g. to docs/doxygen/<your_doxygen_module_name> e.g. in our repo here it lives in docs/doxygen/demo/.

When doing it that way you have a nice separation of the doxygen bits from the rest of the documentation and you have several doxygen documentations in parallel (or in a sub tree structure if you like).



On this page 3 possibilities are shown to link from sphinx/rst files to doxygen documentation.

This is typically used to integrate the doxygen documentation into your own toctree. Definition in rst/md files

rst

.. absolute link to directory
.. toctree::
   /docs/doxygen/demo/html
.. relative link to directory
.. toctree::
   ../doxygen/demo/html
.. absolute link to rst file
.. toctree::
   /docs/doxygen/demo/html/index


myst markdown Definition in rst/md files

just see the navigation of this document. There is a toctree link to the demo module.

This is typically used to reference the root docs or some special page where you know the exact name (Don't use it for C++ Symbols, as there are better ways to link them - see via doxylink symbol links). Definition in rst/md files

rst

.. absolute document link (absolute to sphinx document root dir)
:doc:`/docs/doxygen/demo/html/index`
.. relative document link (relative to the current document)
:doc:`doxygen/demo/html/index`
.. with custom caption
:doc:`C++ Demo Project Doxygen Api Documentation </docs/doxygen/demo/html/index>`


myst markdown

<!-- absolute document link (absolute to sphinx document root dir) -->
{doc}`/docs/doxygen/demo/html/index`
<!-- relative document link (relative to the current document) -->
{doc}`doxygen/demo/html/index`
<!-- with custom caption (myst or plain markdown) -->
{doc}`C++ Demo Project Doxygen Api Documentation <doxygen/demo/html/index>`
[C++ Demo Project Doxygen Api Documentation](/docs/doxygen/demo/html/index)


Output example

rst /docs/doxygen/demo/html/index

doxygen/demo/html/index

C++ Demo Project Doxygen Api Documentation

myst markdown

/docs/doxygen/demo/html/index

doxygen/demo/html/index

C++ Demo Project Doxygen Api Documentation

C++ Demo Project Doxygen Api Documentation

TIP:

As for each doxygen html file an equally named rst file will be created by doxysphinx you can just reference the doxygen sections via their names. However as these aren't always obvious here's a list:
Doxygen page title html/rst name example link (e.g. for toctree or doc link) rendered example
Main Page index /docs/doxygen/demo/html/index /docs/doxygen/demo/html/index
Namespace List namespaces /docs/doxygen/demo/html/namespaces /docs/doxygen/demo/html/namespaces
Class List annotated /docs/doxygen/demo/html/annotated /docs/doxygen/demo/html/annotated
Class Index classes /docs/doxygen/demo/html/classes /docs/doxygen/demo/html/classes
Class Hierarchy inherits /docs/doxygen/demo/html/inherits /docs/doxygen/demo/html/inherits
Class Members functions /docs/doxygen/demo/html/functions /docs/doxygen/demo/html/functions
Files files /docs/doxygen/demo/html/files /docs/doxygen/demo/html/files


When you set up doxylink correctly (see Doxylink Setup) you can link C++ symbols directly from your rst sources.

NOTE:

doxylink "knows" the symbols because in the doxygen tagfile all symbols are mapped to the respective html files.


Definition in rst/md files

rst

.. namespace
:demo:`doxysphinx::rst`
.. class
:demo:`doxysphinx::rst::Car`
.. method
:demo:`doxysphinx::rst::Car::enter(Driver& driver)`


myst markdown

<!-- namespace -->
{demo}`doxysphinx::rst`
<!-- class -->
{demo}`doxysphinx::rst::Car`
<!-- method -->
{demo}`doxysphinx::rst::Car::enter(Driver& driver)`


Output example

rst doxysphinx::rst

doxysphinx::rst::Car

doxysphinx::rst::Car::enter(Driver& driver)

myst markdown

doxysphinx::rst

doxysphinx::rst::Car

doxysphinx::rst::Car::enter(Driver& driver)

You can use rst snippets in all supported doxygen comment styles.

The rst snippets just need to be fenced with the alias tags rst and endrst. However do not nest rst fences. This won't work.

Depending on your preference you can use @rst and @endrst or \rst and \endrst.

Here are some examples (for further examples see doxysphinx::doxygen::CommentStyles).

Variant A - with asterisks

/**
 *\rst
 * .. info
 *    as you can see you can just use directives and anything here
 *
 * also just normal text blocks.
 * Everything inbetween \rst and \endrst will be treated like a normal rst file.
 *\endrst
 */
 void test() const;


Variant B - without asterisks

/**
 \rst
         .. admonition:: Another info
            The indentation will be normalized automatically by doxysphinx.
            However as with any other rst file you should stick to the sphinx indentation rules.
 \endrst
 */
 void test() const;


Variant A - with asterisks

/*!
 *\rst
 * .. info
 *    Qt-style comments also work.
 *\endrst
 *\/
 void test() const;


Variant B - without asterisks

/*!
 *\rst
 *      .. info
 *         Qt-style comments without asterisk and indentation also work
 *\endrst
 *\/
 void test() const;


Variant A - tripple slashes (microsoft style)

/// @rst
///
/// ...rst-content-here...
///
/// @endrst
void test() const;


Variant B - double slash exclamation mark

//! @rst
//!
//!         ...rst-content-here...
//!
//! @endrst
void test() const:


😲 TODO - add needs traceability docs.

In general, you should have vscode installed (which is fully supported by us).

We provide a dev container which might be a little more frictionless (because all dependencies are installed automatically in an isolated environment) or standard non container development.

What is better for you comes down to your personal preferences.

WARNING:

if you're on windows... You should be careful not to mount your windows filesystem into wsl2 / the devcontainer because this will be slow as hell regarding file io. This will be automatically the case if you clone your repo on a windows drive, open it in vscode and then open the devcontainer. Instead you can use one of the following approaches:
  • Clone your repo in wsl2 in the native wsl2 filesystem (not beginning with /mnt) and open it from there: Open a wsl2 folder in a container on Windows
  • Clone your repo directly in a new docker volume (which also happens to live in the wsl2 filesystem): Open a git repository or github pr in an isolated container volume



Open the repo in vscode devcontainer and follow the steps in the Usage section.

This is a little more work because you need to arrange prerequisites first.

In addition to the prequisites defined in the Getting Started Guide install the following tools if you haven't them yet:

  • Poetry Installation (see also https://python-poetry.org/docs/master/#installation)

    Linux/Mac

curl -sSL https://install.python-poetry.org | python3 -


Windows

(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -



devcontainer

  • open the devcontainer
  • if you installed the devcontainer cli just cd into the repo and type:

devcontainer build  # for initially building or rebuilding the devcontainer
devcontainer open   # for opening the devcontainer directly in vscode


  • if not you can open vscode by typing:

code


When vscode opens you should see a notification asking you if you want to reload vscode in devcontainer - acknowledge it. (If that's not working keep sure that you installed the remote container extension in vscode on your host).



native development (windows, linux, etc.)

  • Open the repo in vscode
  • On first start: install poetry packages and precommit hooks with vscode terminal (may take some time)

poetry install
poetry run pre-commit install --install-hooks


  • in vscode select the python interpreter (Command Palette -> Python: Select Interpreter - if the poetry virtual env created before isn't shown restart vscode and retry)

  • now you're ready to develop
  • you can just hit F5 and should be able to debug into the code
  • you can also use the testrunner to run the unittests (or write some more for all the great features you're implementing now 😉)
  • in vscode there are some tasks defined to manually run the precommit, lint etc. (usually you won't need that if you installed precommit hooks)

  • For testing the doxysphinx cli you can also run it directly in the vscode terminal:

poetry run doxysphinx <args...>


  • For just generating docs you can use the normal sphinx makefile mechanisms (A user would also do the same):

make html # build complete documentation (doxygen, doxysphinx, sphinx)
make help # show commands
make clean # cleanup
make [doxygen|doxysphinx|sphinx] # run steps separately


You can then see the generated documentation by opening .build/html/index.html.


If you want to update the projects dependencies do the following:

  • checkin/stash all your local changes (so you could reverse easily and see the differences quite easy)
  • update your dependencies:

poetry up --latest --without ci


  • review the updates e.g. in vscode with git diff
  • test everything 😄

If you get module not found errors, e.g. when running doxysphinx or sphinx the problem might be the vscode terminal. Sometimes vscode isn't activating the poetry virtualenv correctly in terminal (even if the rest of vscode is working). The solution is then to just restart the terminal (note that in the devcontainer you should use the zsh terminal).

[image: screenshot on windows] [image]

Watch out for an venv activate script call or for the changed command prompt (the venv name should be at the beginning of the prompt).

HINT:

Should be the same for Intellij Idea.


While we recommend using vscode there are times when pycharm may be a better fit/ may be better suited for some dev tasks.

When opening the project in pycharm you may need to select the poetry executable. Under Windows this is installed in %USERPROFILE%\AppData\Roaming\Python\Scripts\poetry.exe (This path is as the time of this writing documented wrong in the poetry documentation so we mentioned that here).

Initialization will take some time in pycharm (especially when indexing the python sdk) so please be patient until everything is set up (watch the right side of the pycharm status bar).

We provide the makefile targets as run configurations. As Make is no standard tool under windows you would need to install it (e.g. via chocolatey "choco install make"), and afterwards configure it in Pycharm under File->Settings->Build, Execution, Deployment->Build Tools->Make->Path to Make executable.

Doxysphinx is a click cli application.

The main entrypoint to doxysphinx is the cli module and the commands defined in it:

  • build (which builds the rst files for doxygen)
  • clean (which removes any file created from doxysphinx)

These commands take the sphinx_source_directory the sphinx_output_directory and at least one doxygen config file (doxyfile) as input to do their work.

During build command doxysphinx follows these steps:

  • A builder is created (for now there's only one Builder. But in the future there may be more)
  • This builder represents the whole rst generation/building process which has these phases:
  • Resource Provisioning:

    In this step html resources (images, stylesheets, javascript files etc.) are copied to the output directory and adapted. The input and output directories are mapped with the help of a DirectoryMapper.

  • Building Rst Files:

    Each HTML file found in the doxygen output is parsed (with a HtmlParser) and written to an rst file (with a Writer).



[image]

1.
Doxygen html output is parsed. This is implemented in DoxygenHtmlParser. The Parser will parse load the html file, do some processing (it will extract some metadata and change <pre>- and <verbatim>-tags into more generic <rst>-tags) and creates a HtmlParseResult that contains the metadata and the processed DOM as an etree.
2.
For each doxygen html file a rst file is created based on the following rules (see RstWriter.write(...)):
  • If the html file doesn't contain any rst documentation blocks an rst with a raw include directive is written. This will directly put the html file into the output (but with sphinx templating/toc etc. "around").
  • If the html file contains at least one \rst (or @rst) documentation element it is "splitted" at these rst documentation snippets. For each html segment a raw html directive with the html as content is then written and each rst segment is written directly.
  • The rst files are written in parallel to the html files with the same name but the rst suffix instead of the html suffix.
  • The RstWriter will also create a toctree for some rsts based on the DoxygenTocGenerator implementation.

3.
When sphinx processes these rst files it will render the results as html to it's own output directory thereby keeping the original file name which means that all doxygen internal links stay intact.

  • As the sphinx raw html directive isn't considering resources (css, images, javascript-files etc.) these files are copied to the output directory if they are newer (this is done at the beginning of the process) - see DoxygenResourceProvider.
  • In the ResourceProvider we also patch the doxygen.css file via libsass to scope it below a special div-element (()) and add some extra css rules which change some theme css styles. For the scoping see CssScoper.

Hey, if read this far you have to be a developer - Just fire up your IDE and look into the code 😊.

This is the api reference for doxysphinx.

Doxysphinx main package.

Doxysphinx uses click to provide a command line interface with sub commands similar to e.g. git.

The main command is doxysphinx.cli.cli(). The build and clean commands are defined in doxysphinx.cli. The commands itself will do some input validation and then call into the doxysphinx.process.Builder which is considered the entrypoint of the main doxysphinx functionality.

Entry module for the doxysphinx cli.

Defines click main command (cli()) and subcommands (build()), (clean())

NOTE:

  • Execute this script directly to start doxysphinx.
  • If you need to call a function to start doxysphinx (e.g. for vscode launch config etc.) use the cli() directly.
Sphinx autodoc which created this documentation seems to have problems with decorated methods. The function signatures shown here in the documentation aren't correct. Just click on view source to see the correct signatures.





DoxygenContext Represent the options for doxygen that can be set via the cli.

cli() Integrates doxygen html documentation with sphinx.
build(parallel, sphinx_source, sphinx_output, **kwargs) Build rst and copy related files for doxygen projects.
clean(parallel, sphinx_source, sphinx_output, **kwargs) Clean up files created by doxysphinx.

Module Contents

Represent the options for doxygen that can be set via the cli.

The doxygen projects are specified through INPUT (multiple possible). INPUT can be:

  • a doxygen configuration file (aka doxyfile)
  • a directory, which contains the generated doxygen html documentation. Note that specifying a directory will skip the config validation completely and is therefore considered "advanced stuff". You will typically want to use that if you're integrating doxysphinx in a ci build system. If unsure, use a doxyfile.





Integrates doxygen html documentation with sphinx.

Doxysphinx typically should run right after doxygen. It will generate rst files out of doxygen's html files. This has the implication, that the doxygen html output directory (where the rst files are generated to) has to live inside sphinx's input tree.


Build rst and copy related files for doxygen projects.

SPHINX_SOURCE specifies the root of the sphinx source directory tree while SPHINX_OUTPUT specifies the root of the sphinx output directory tree.

WARNING:

  • when using sphinx-build -b html SOURCE_DIR OUTPUT_DIR ... the html output will be put to OUTPUT_DIR so so doxysphinx's SPHINX_OUTPUT should be OUTPUT_DIR.
  • when using sphinx-build -M html the html output will be put to OUTPUT_DIR/html so doxysphinx's SPHINX_OUTPUT should be OUTPUT_DIR/html.




Clean up files created by doxysphinx.

SPHINX_SOURCE specifies the root of the sphinx source directory tree while SPHINX_OUTPUT specifies the root of the sphinx output directory tree. The doxygen html outputs are specified through INPUT (multiple possible) either by pointing to the doxygen html output directory or by pointing to the doxygen config file (doxyfile).


The doxygen module contains classes and functions specific to doxygen.

ConfigDict

DoxyOutput Class to summarize the strings of the console output and error streams.
DoxygenSettingsValidator Validate doxygen settings for compatibility with doxysphinx.
DoxygenOutputPathValidator Validates doxygen html output paths.

read_doxyconfig(→ ConfigDict) Read doxyconfig and get full doxygen configuration (also with default values).
read_js_data_file(→ Any) Read a doxygen javascript data file (e.g. menudata.js) and returns the data as json structure.

Module Contents


Class to summarize the strings of the console output and error streams.



Read doxyconfig and get full doxygen configuration (also with default values).

Supplement the doxygen configuration file with the default doxygen configuration and return the final key value pairs as a dict.

  • doxyfile -- the doxygen configuration file to read
  • doxygen_exe -- in case one wants to execute doxygen from another directory.

a dict representing all key-value pairs defined in the final configuration (including warnings from the console output). The value can either be a single value or a list.


Validate doxygen settings for compatibility with doxysphinx.

Doxysphinx requires some settings to be present/set in a specific way.

A dictionary containing mandatory settings for the doxygen config. The values of OUTPUT_DIRECTORY and GENERATE_TAGFILE will be set after instantiation and validation of the filepaths.

A dictionary containing further optional settings for the doxygen config.

List of the validation errors including the doxyflag with its used and the correct value.

Absolute path of the output directory.

Validation errors merged in one string.

Validate the doxygen configuration regarding the output directory, mandatory and optional settings.
  • config -- the imported doxyfile.
  • sphinx_source_dir -- the sphinx directory (necessary for output directory validation).
  • doxygen_cwd -- the directory for doxygen, paths from doxyfile are relative from here

False, if there is a deviation to the defined mandatory or optional settings.



Read a doxygen javascript data file (e.g. menudata.js) and returns the data as json structure.
js_data_file -- The doxygen js data file to use.
a json like dict of the data.


Validates doxygen html output paths.

Validate a doxygen html output path.

This is just meant to catch typos in paths etc. It will just check if a "doxygen.css" file is existing In the html output path.

doxygen_html_output -- The path where doxygen generates its html file to.
True if the path is valid else false.



The html_parser module contains the html parser that will load and process the html files.

To allow several writer implementations to pick up and handle the result of that parsing a html parser in a neutral way the parser will change all relevant rst/sphinx markup elements to <snippet>-elements.

HtmlParseResult Capsules a parsed and processed html tree with meta information.
HtmlParser Html Parser Protocol for parsing html files into a neutral format (that can be then processed further).
ElementProcessor An ElementProcessor processes specific html elements, one at a time.
RstInlineProcessor Element Processor for inline rst elements.
RstBlockProcessor Element Processor for rst block elements.
PreToDivProcessor This Element Processor will change <pre>-tags to <div class="fragments"> tags.
MarkdownRstBlockProcessor Element Processor for doxygen markdown block elements.
DoxygenHtmlParser Parser for Doxygen HTML output files.

Module Contents

Capsules a parsed and processed html tree with meta information.
The html file that was parsed.

The project where this html file belongs to. This can be e.g. a directory name or a component/module name etc.

The html meta title if present in the original html. If not just set to document title

The document title. This is the title that is visible e.g. in sphinx menu structure.

The list of snippet formats that are used inside the html tree if any.

The html/xml element tree or None if nothing was parsed because the html shouldn't be handled as mixed mode content.


Bases: Protocol

Html Parser Protocol for parsing html files into a neutral format (that can be then processed further).

You own html parser should find/generate all rst-content in <rst>-tags. The further tooling can then work with that.

Parse a html file.

This method returns a ParseResult (Tuple[bool, _ElementTree]). The first item in the tuple indicates if rst data was found during parsing. The second item is the parsed and normalized html as ElementTree. It is expected that all rst data in this resulting ElementTree is present in special <rst>-tags.

file -- The html file to parse
The result of the parsing



Bases: Protocol

An ElementProcessor processes specific html elements, one at a time.

Typically this is used to either clean up or transform the elements into a neutralized format.

A list of html element names this processor can process.

This is for pre-filtering html elements (an optimization). This processors try_process method is only called on these elements.


Whether other processors should be called after this one.

With a "final processor" (is_final == True) processing of an element stops (no other processors considered) once the try_process method returns True.


The format this element processor processes... like 'rst', 'md' etc.

Try to process an element.
element -- The element to check and process
Whether the "processor did it's thing"/"processing was applied" (True) or not (False)



Element Processor for inline rst elements.




Try to process an rst inline element into a neutralized format.
element -- The html element to process
True if the element was processed else False



Element Processor for rst block elements.



Try to process an rst block element into a neutralized format.
element -- The html element to process
True if the element was processed else False



This Element Processor will change <pre>-tags to <div class="fragments"> tags.

We do this because doxysphinx will linearize html output in the writer to have it in one line in the raw html directive. However this will destroy the newlines in pre tags. To overcome that We change the pre output here to a div with inner line divs (which is also supported by doxygen).

This processor is special because it should only run when any other processor has done something.




Transform a pre element into a div element.
element -- The html element to process
True if the element was processed else False



Element Processor for doxygen markdown block elements.

This processor will check if the first line in the markdown block is either a supported marker or a directive (auto detection feature).

Markdown block elements in doxygen are getting rendered different to verbatim content. Each Markdown block (delimited with 3 backticks) will be something like this in html:

<div class="fragment">
  <div class="line">{rst}</div>
  <div class="line">This is rst content</div>
  <div class="line"> </div>
  <div class="line">anything can be used here...</div>
  <div class="line"> </div>
  <div class="line">like an admonition:</div>
  <div class="line"> </div>
  <div class="line">..admonition::</div>
  <div class="line">  </div>
  <div class="line">  test</div>
</div>





Try to process an rst block element into a neutralized format.
element -- The html element to process
True if the element was processed else False



Parser for Doxygen HTML output files.
Parse a doxygen HTML file into an ElementTree and normalize its inner data to contain <rst>-tags.
file (Path) -- The html file to parse
The result of the parsing
ParseResult



The process module contains the Builder and Cleaner classes.

These represent the main functionality of doxysphinx.

Builder The Builder builds target docs-as-code files out of an existing html documentation.
Cleaner The cleaner cleans files created and copied by the builder.

Module Contents

The Builder builds target docs-as-code files out of an existing html documentation.

For each an every html file a rst file is created that imports the html content with raw directives. The html resources (stylesheets, images etc.) are also processed and copied to the correct place in the sphinx output directory. When sphinx then (later - not part of doxysphinx) processes the rst files they will resemble the original filenames in the sphinx output directory, thereby keeping and internal links intact.

Generate a rst file for each doxygen html file.

Also copies necessary resources.

doxygen_html_dir -- The html output directory of doxygen where the generated documentation is.



The cleaner cleans files created and copied by the builder.
Clean up files that were generated by the build method.
doxygen_html_dir -- The html output directory of doxygen where the generated documentation is.



The resources module contains classes will do resource provisioning and patching.

Resources are stylesheets, images, javascripts etc. that contemplate the html files.

ResourceProvider A resource provider copies/adapts necessary resources (images, stylesheets, etc.) to output.
DoxygenResourceProvider Resource provider that will copy/adapt doxygen html resources to output.
CssScoper Scopes css-stylesheets to a special selector.

Module Contents

Bases: Protocol

A resource provider copies/adapts necessary resources (images, stylesheets, etc.) to output.

Provide necessary resources to sphinx output directory.

Can also do postprocessing etc.

resource_root -- the root resource input directory (e.g. where the html files are located)
A list of resources (their target paths) that were copied/provided. Note that in case of some caching (copy if newer) mechanisms this might return only parts of the resources.


Clean up provided resources that were copied by provide_resources().
resource_root -- the root resource input directory (e.g. where the html files are located)
A list of resources (their target paths) that were cleaned up/removed.



Resource provider that will copy/adapt doxygen html resources to output.

Resource are e.g. stylesheets, images, javascript files etc.

Copy doxygen html resource files (see GLOB_PATTERN below) to sphinx output.

The content in the raw html directives can then access these directly.



Clean up any provisioned resources that were copied to sphinx output.


Scopes css-stylesheets to a special selector.

This is done with the help of libsass (as the sass-syntax extends css with nesting).

Our original problem was that the doxygen stylesheet and the sphinx theme stylesheets collide in some ways (e.g. global styles like heading-styles etc...). We therefore needed to have a mechanism to apply doxygen stylesheets only to doxygen content (not to the outer sphinx theme shell). We do this via sass, because sass is css compatible but adds some nice features to it. You can for example nest styles. We use that here to define an outer class and nest the whole doxygen stylesheet below it in a temporary sass stylesheet which then gets compiled back to css. With this we kill 2 birds with one stone: * all doxygen rules are now scoped so they are not applied to the sphinx bits shell anymore.... * all doxygen rules now are more specialized than any of the outer sphinx style rules (they will win in browser).

In the end that means that sphinx styles are applied to sphinx bits and doxygen styles are applied to doxygen bits. We still need to fix some minor issues with a custom stylesheet (which we also apply here).

Scope a stylesheet to given selector.

The process is as follows: The original stylesheet is read, processed, hashed and compiled to the target. If a target already exists and the hash is identical nothing is compiled and written.

  • stylesheet -- The path to a stylesheet to scope.
  • additional_css_rules -- Additional css rules to inject.
  • scss_patch_callback -- A callback that will be called on the original file. Note: we had a bug in doxygen.css and a sass compatibility fix for doxygen-awesome that made this mechanism necessary. With one of the recent doxygen versions the doxygen.css bug was fixed however we still keep it here some time.

target: The path to a stylesheet where the results are written to.
The path to the written stylesheet (should be identical to stylesheet).



The sphinx module contains classes that are tied to sphinx or resemble sphinx logic.

DirectoryMapper Mapper that will calculate the output file path for an input file.
SphinxHtmlBuilderDirectoryMapper Mapper that will calculate the output file path for an input file.

Module Contents

Bases: Protocol

Mapper that will calculate the output file path for an input file.

In docs-as-code tooling (e.g. sphinx) often files from a source dir structure are processed and written to result files in a target dir structure.

The make this mapping an implementation detail this protocol exists. It should be implemented for any special handling in mapping files.

Calculate the path in output for a given path in input.


Mapper that will calculate the output file path for an input file.

This is based on the logic that the sphinx html builder would use.



Calculate the path in output for a given path in input.


The toc module contains classes related to the toctree generation for doxygen htmls/rsts.

TocGenerator TocGenerator protocol.
DoxygenTocGenerator A TocGenerator for doxygen.

Module Contents

Bases: Protocol

TocGenerator protocol.

Gets the source_dir (with the html sources) during init and each file to possibly generate a toctree directive for in the generate_toc_for() method. The implementer has then to choose how to implement the toc generation.

Generate a toctree directive for a given file.
file -- the file to generate the toctree directive for
a string interable representing the lines forming the toctree directive



A TocGenerator for doxygen.

Will read the menudata.js to check whether a toctree directive needs to be generated or not.

Generate a toctree directive for a given file.

Note that the toctree will only be generated when the file is part of a menu structure. :param file: the file to generate the toctree directive for :return: a string iterator representing the lines forming the toctree directive



Utils package with several helpers not related to main application logic.

The contexts module contains several python context manager related functions.

TimedContext A context manager to measure elapsed time.

Module Contents

Bases: object

A context manager to measure elapsed time.

Use it to measure the time taken to process the inner code.

Usage:

Get the elapsed time.
The duration.


Get the elapsed time as a "humanized" format.
A humanized string of the elapsed time - Something like "3 days 5 hours 17 minutes".



The exception module contains several standard exceptions.

ApplicationError A generic application error.
ValidationError A generic error to indicate some validation failed.
PrerequisiteNotMetError An application error that indicates that some prerequisite is not met.

Module Contents

Bases: Exception

A generic application error.


Bases: Exception

A generic error to indicate some validation failed.


Bases: Exception

An application error that indicates that some prerequisite is not met.


The files module contains several file related helper functions.

write_file(file, data[, separator]) Write an array of lines to a file in one call.
replace_in_file(file, search, replacement) Replace a text in a file.
multi_replace_in_file(file, *search_replace_pair) Replace text inside a file. Supports multiple replacements.
multi_glob(→ List[pathlib.Path]) Evaluate multiple glob patterns at once.
copy_if_different(→ List[pathlib.Path]) Copy files with given glob patterns from source_dir to target_dir but only if the files are different.
stringify_paths(→ str) Convert a list of paths to a bulleted string where each path is on a new line.
hash_blake2b(→ str) Fast file hash based on blake2b hash algorithm.

Module Contents

Write an array of lines to a file in one call.
  • file -- The path to the file.
  • data -- An array of lines to write to the file.
  • separator -- The line separator. Defaults to os.linesep = autodetect for current os. If you want to force a unix "lf" file use 'n', if you want to force a windows "crlf" file use 'rn'., defaults to None



Replace a text in a file.
  • file -- The file to do the replacement in.
  • search -- The text to search inside the file.
  • replacement -- The replacement text.



Replace text inside a file. Supports multiple replacements.
  • file -- The file to do the replacement in.
  • search_replace_pair -- an argument list of search and replacement text pairs.



Evaluate multiple glob patterns at once.
  • directory -- The source directory (where to evaluate the glob pattern)
  • patterns -- The glob patterns as list or multi-arguments

The list of found files/directories


Copy files with given glob patterns from source_dir to target_dir but only if the files are different.


  • source_dir -- The source directory of the files to copy
  • target_dir -- The target directory where the files are copied to
  • patterns -- glob patterns for the source files

a list of all files that were copied (target files)


Convert a list of paths to a bulleted string where each path is on a new line.

Fast file hash based on blake2b hash algorithm.
  • file -- Path to a file to calculate the hash for
  • chunk_size -- The size of the chunks that are read from the file. Use this if you really need to optimize for performance for your special use case. Note that the default (64k) turned out the fastest in some very naive adhoc tests... so there may be room for improvement here.



The iterators module contains several iterator related helper functions.

T
Predicate
Action

apply_if(iterable, check, action) Apply the action function to each element that matches the predicate.
apply_if_first(iterable, check, action) Apply the action function to the first element that matches the predicate.
apply(→ None) Apply the action function to all elements.

Module Contents




Apply the action function to each element that matches the predicate.
  • iterable -- The input iterable (list etc...)
  • check -- The predicate to check
  • action -- The action to apply



Apply the action function to the first element that matches the predicate.
  • iterable -- The input iterable (list etc...)
  • check -- The predicate to check
  • action -- The action to apply



Apply the action function to all elements.
  • iterable -- The input iterable (list etc...)
  • action -- The action to apply



The pathlib_fix module contains several pathlib fixes.

path_resolve(→ pathlib.Path) Fix/Workaround for bug https://bugs.python.org/issue38671.
path_is_relative_to(→ bool) Fix/Workaround for strange behavior in python 3.8.

Module Contents

Fix/Workaround for bug https://bugs.python.org/issue38671.

On Windows resolve will not return correct absolute paths for non-existing files (only for existing ones). This got fixed in python 3.10, however as we need to support older versions....


Fix/Workaround for strange behavior in python 3.8.

The issue is that Path.is_relative_to complains about PosixPath not having such an attribute in a foreign project.


The rst module contains rst specific helpers.

rst_safe_encode(→ str) Encode text to be rst safe (special chars will get escaped correctly).

Module Contents

Encode text to be rst safe (special chars will get escaped correctly).
text -- The text to encode.
The rst safe encoded text


The writer module contains classes that write the docs-as-code output files.

Writer Protocol representing a Writer that write docs-as-code files.
RstWriter Writes sphinx-rst files to disk.

Module Contents

Bases: Protocol

Protocol representing a Writer that write docs-as-code files.

Write a parsed html result to a target file.

The format of that file is controlled by the concreate Writer implementation.

  • parse_result -- The result of a previous html parser run
  • target_file -- The target file to write

The written file (should be always identical to target_file input, but allows chaining...)



Writes sphinx-rst files to disk.
Write html content to the target_file.
  • parse_result -- The result of the html parsing (=content + metadata)
  • target_file -- The target docs-as-code (e.g. rst) file

The path the file was written to.



First of all, thanks for considering contributing to this project!! Your help is highly appreciated!!

So this document got quite long... here is the very short summary/checklist:

  • [ ] don't commit on main - use pull requests only
  • [ ] use this branch naming convention: feature/#39_bring_the_unicorns_back
  • [ ] commits must adhere to the conventional commits spec.
  • [ ] add copyright header to new file or add yourself as author in existing files.
  • [ ] sign your commits with a developer certificate of origin (dco) - (git commit -s -m "MESSAGE") or use vscode which is configured for the repo to do this automatically.
  • [ ] only once: add yourself as a contributor to NOTICE.md.

Use pull requests to contribute to this repository.

Pushes to the main branch are automatically rejected.

Keep your PRs focussed on a single purpose. For example, do not implement multiple features or fix multiple bugs in a single PR unless they are interconnected. Simply create separate PRs instead.

Branches should be named with this scheme:

group/short_description


The group denotes the purpose of the contribution:

  • feature: A new feature
  • fix: A bug fix
  • ci: GitHub workflow only changes
  • docs: Documentation only changes

The short description should describe the change/feature etc. If you have a bigger change please create an issue here in github and use the number as short description, e.g. feature/#39_bring_the_unicorns_back

We use Conventional Commits to automatically calculate the semantic version, create the changelog, and publish the release via Python-Semantic-Release tooling.

The following is a slightly adapted version (to doxysphinx) of the excellent Angular commit style.

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type, a scope and a subject:

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>


The header is mandatory and the scope of the header is optional.

Any line of the commit message should not be longer than 100 characters!. This allows the message to be easier to read on GitHub as well as in various git tools.

Must be one of the following:

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing or correcting existing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

The scope could be anything specifying place of the commit change. For example parser, writer, config, examples, cli etc...

You can use * when the change affects more than a single scope or just leave (<scope>) out completely.

The subject contains succinct description of the change:

  • use the imperative, present tense: "change" not "changed" nor "changes"
  • don't capitalize first letter
  • no dot (.) at the end

Just as in the subject, use the imperative, present tense: "change" not "changed" nor "changes". The body should include the motivation for the change and contrast this with previous behavior.

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit closes.

Breaking Changes should start with the word BREAKING CHANGE: with a space or two newlines. The rest of the commit message is then used for this.

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.

  • a very short new feature commit message:

feat: add button that brings the unicorns back


  • a multiple changes (just add a newline and repeat the pattern) + breaking change commit message:

feat(config): config file support
Now we established our own configuration file mechanism. The previous command line argument based
mechanism forced the users to always create a script, use makefiles etc. With the new mechanism only a
config file needs to be given. Config can be read from yml, toml and json files. As we're often dealing with
python projects there is also special support for pyproject.toml.
fixes #59
BREAKING CHANGE: cli arguments aren't supported anymore.
docs(config): document config mechanism
The new config mechanism is documentation in our sphinx documentation.



Include a copyright notice and license consistent with the style used by this project. If your contribution contains code under the copyright of a third party, document its origin, license, and copyright holders.

Typically for code this would be through a header. You can use this as a template: .copyright.tmpl

This project also tracks patch provenance and licensing using the Developer Certificate of Origin and Signed-off-by tags initially developed by the Linux kernel project.

Developer Certificate of Origin
Version 1.1
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
1 Letterman Drive
Suite D4700
San Francisco, CA, 94129
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or
(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or
(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.
(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.


With the sign-off in a commit message you certify that you authored the patch or otherwise have the right to submit it under an open source license. The procedure is simple: To certify above Developer's Certificate of Origin 1.1 for your contribution just append a line

Signed-off-by: Random J Developer <random@developer.example.org>


to every commit message using your real name or your pseudonym and a valid email address.

If you have set your user.name and user.email git configs you can automatically sign the commit by running the git-commit command with the -s option. There may be multiple sign-offs if more than one developer was involved in authoring the contribution.

Often employers or academic institution have ownership over code that is written in certain circumstances, so please do due diligence to ensure that you have the right to submit the code.

If you are a developer who is authorized to contribute to Ontology Central on behalf of your employer, then please use your corporate email address in the Signed-off-by tag, otherwise use a personal email address.

Each contributor is responsible for identifying themselves in the NOTICE.md file, the project's list of copyright holders and authors. Please add the respective information corresponding to the Signed-off-by tag as part of your first pull request.

If you are a developer who is authorized to contribute to Ontology Central on behalf of your employer, then add your company / organization to the list of copyright holders in the NOTICE.md file. As author of a corporate contribution you can also add your name and corporate email address as in the Signed-off-by tag.

If your contribution is covered by this project's DCO's clause "(c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it", please add the appropriate copyright holder(s) to the NOTICE.md file as part of your contribution.

This is completely optional but we strongly recommend to install doxylink for linking from sphinx documentation directly to doxygen documented symbols like functions, classes etc.

Install pip package:

pip install sphinxcontrib-doxylink


Activate the doxylink extension in your sphinx conf.py:

extensions = [
  # all the other extension
  "sphinxcontrib.doxylink",
]


Doxylink "knows" the c++ symbols by reading tagfiles that are generated by doxygen (this is also the reason why tagfiles need to be enabled in doxygen config - see Step 2: Prepare Doxygen Config).

You now need to register your doxygen documentations with in your sphinx conf.py with doxylink with the doxylink variable:

doxygen_root = "docs/doxygen" # this is just a convenience variable
doxylink = {
    "demo": (  # "demo" is the role name that you can later use in sphinx to reference this doxygen documentation (see below)
        f"{doxygen_root}/demo/html/tagfile.xml", # the first parameter of this tuple is the tagfile
        f"{doxygen_root}/demo/html", # the second parameter of this tuple is a relative path pointing from
                                     # sphinx output directory to the doxygen output folder inside the output
                                     # directory tree.
                                     # Doxylink will use the tagfile to get the html file name of the symbol you want
                                     # to link and then prefix it with this path to generate html links (<a>-tags).
    ),
}


Register all your doxygen documentions via this mechanism. In your rst files you can then use e.g. (as documented here: https://sphinxcontrib-doxylink.readthedocs.io/en/stable/)

The class :demo:`doxysphinx::rst::Car` implements the car.


🎉 Congratulations you've completed the doxylink setup.

Related topics:

  • To get to know the doxysphinx setup -> see our doxysphinx guide.

Welcome to the Doxysphinx documentation!

Doxysphinx is a doxygen and sphinx integration tool.

It will make the doxygen documentation appear inside the sphinx documentation: [image: doxysphinx result examples screenshot] [image]

It comes as an easy-to-use cli tool and typically runs right after doxygen created it's html documentation. Doxysphinx creates restructured text (.rst) files out of these (doxygen) html files. Afterwards sphinx will pick up these rst files and create an integrated documentation (sphinx theming is applied, search etc.). [image: doxysphinx integration process] [image]

Doxysphinx is also a traceability enablement tool because as doxygen documentation gets integrated with sphinx you can e.g. define and reference sphinx-needs objects to link requirements, architecture elements, etc. directly in and to your source code.

With that it can be also seen as a little cog in the docs-as-code gear.

  • Reuses doxygens html output...
  • Graphics are working (hierarchies, etc.)
  • Doxygen's structure and views are preserved - namespaces, indexes, code views etc.

  • Integration in sphinx brings...
  • Sphinx Theming/Frame applied
  • Sphinx full text search over the doxygen documentation

  • Use sphinx enabled (directives, extensions, etc.) restructured text snippets in doxygen comments
  • This allows for example to define and reference sphinx need objects like requirements, components etc. down in the source code to get full tracability.


  • Right now doxysphinx is developed against the sphinx-book-theme and the sphinx-rtd-theme.

    Other Themes might work but aren't styled explicitly.

  • Furo theme will unfortunately not work because of some quality-gates in Furo which check for header-tags in output. As doxygen html has such tags and we integrate it directly it won't work with furo.
  • Doxysphinx can only include complete doxygen pages. If you want to embedd e.g. a single class or method documentation inline in your docs please take a look at Breathe or the other alternatives.

Author name not set