oneAPI Construction Kit uses the Sphinx documentation generator,
setup of the required tooling is performed during CMake configuration and
output in the<build>/doc
directory. To build the documentation, use the
doc_html
build target.
While reStructuredText is preferred for new documents a significant
amount of the documentation was written before switching to using
Sphinx. To support this the Markedly Structured Text (MyST)
extension is used and any files which use the .md
file extension will be
parsed as Markdown. MyST then translates the Markdown into a format
Sphinx understands internally.
It is also possible to use reStructuredText features from within a Markdown document as described in the MyST Syntax Guide.
An example of using an admonition directive in a Markdown document:
:::{warning}
This is an admonition warning the reader of something to be wary of, it will
be rendered with an orange background to grab their attention.
:::
There is also support for Markdown tables using the sphinx-markdown-tables extension.
The C and C++ header files in the oneAPI Construction Kit are largely documented
using [Doxygen][doxygen] comments. These are parsed by [Doxygen][doxygen] which
is configured to output XML files in the <build>/doc/xml
directory. To
integrate this information into the generated documentation the breathe
extension is used.
breathe has it's drawbacks, the maintainers are not very active and
there are known performance issues due to dependency on a deprecated Python XML
parsing package which leaks memory. To speed up iteration times when working on
non-Doxygen documentation a work around is to temporarily delete
doc/api-reference.md
and use the sphinx-build
build target which skips any
use of [Doxygen][doxygen] and breathe.
KitWare, the creators of CMake, use Sphinx to generate their documentation. The extension sphinxcontrib.moderncmakedomain provides this integration which we can use to write reStructedText directly within CMake files.
#[=======================================================================[.rst:
.. cmake:variable:: CMAKE_BUILD_TYPE
A CMake option to specify the type of executables to build.
#]=======================================================================]
Note that these comment lines are special, denoting a block of reStructuredText inside the CMake file.
To include a CMake module in the documentation, it must be included using:
.. cmake-module:: ../relative/path/to/the/file.cmake
There are two other useful directives we can use to document the build system, for example:
.. cmake:variable:: ENABLE_MY_TARGET
A boolean CMake option to enable adding my fancy target.
.. cmake:command:: add_my_target
A CMake command to add my fancy target.
Arguments:
* ``target`` The name of the target to add.
Keyword Arguments:
* ``COMMAND`` The commad to for the target to invoke.
It is also possible to cross-reference existing or not yet existing variables and commands inline using the following syntax:
Enable :cmake:variable:`ENABLE_MY_TARGET` to make :cmake:command:`add_my_target`
available.
When a section is incomplete, out of data, or otherwise requires more work use the following reStructuredText syntax to render a visually obvious todo block.
.. todo::
:jira:`CA-1` write this section
It is also possible to build PDF documents of the documentation, do to this the following packages must be installed:
$ sudo apt install latexmk texlive-xetex xindy texlive-fonts-extra