Skip to main content
`Ctrl`+`K`

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

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

/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

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