source

dox_util provides several ways to reference source code.

Including a Source File

The Sphinx built-in literalinclude has an unpleasant downside. The path in RST and therefore in HTML is relative to the rst-file, so typically some “..” are included.

With sourceinclude from this extension it is possible to specify files relative from the folder above doc.

Comparison example:

<module_root>/doc/sub/page.rst
<module_root>/include/mod/example.h

.. literalinclude:: ../../include/mod/example.h
    :start-after: MARKER1
    :end-before: MARKER2
    :language: c++
    :dedent: 4
    :caption:

.. sourceinclude:: include/mod/example.h
    :start-after: MARKER1
    :end-before: MARKER2
    :language: c++
    :dedent: 4
    :caption:

In case no doc folder is in the path between Sphinx root and the rst-file, the source file can also be specified relative to the rst-file.

Referencing a Source File

To simply reference a source file use :source:`<relative path to file>`. The result will be a highlighted string, not a clickable reference. The path is relative to the module root, similar to sourceinclude. This role checks for existence of the file. In case the file does not exist, an error is returned.

Example:

:source:`source/include/MemoryManager.h` results in source/include/MemoryManager.h.

Note, that Sphinx has a built-in type :file:. It does no existence check and it is relative to the rst-file.

Example:

:file:`source/include/DoesNotExist.h` results in source/include/DoesNotExist.h.