Linking to Doxygen

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 serveral 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.

inside a toctree directive

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.

via document link

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

Demo

Demo

C++ Demo Project Doxygen Api Documentation

myst markdown

Demo

Demo

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	Demo
Namespace List	namespaces	/docs/doxygen/demo/html/namespaces	Namespace List
Class List	annotated	/docs/doxygen/demo/html/annotated	Class List
Class Index	classes	/docs/doxygen/demo/html/classes	Class Index
Class Hierachy	inherits	/docs/doxygen/demo/html/inherits	Class Hierarchy
Class Members	functions	/docs/doxygen/demo/html/functions	Class Members
Files	files	/docs/doxygen/demo/html/files	File List

via doxylink symbol links

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)