Overview#
Welcome to the Doxysphinx documentation!
What is Doxysphinx?#
…an integration tool#
Doxysphinx is a doxygen and sphinx integration tool.
It will make the doxygen documentation appear inside the sphinx documentation:
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.).
…a traceability enablement tool#
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.
Features#
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.
Caveats#
Right now doxysphinx is developed against the sphinx-book-theme and the sphinx-rtd-theme.
Other Themes might work but aren’t styled explicitely.
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.