Skip to content

Files

Latest commit

9e2fcab · Feb 10, 2025

History

History

doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
May 29, 2023
Feb 14, 2024
Jan 17, 2025
Oct 21, 2024
Jun 19, 2023
Feb 14, 2024
Jan 17, 2025
Feb 14, 2024
Feb 7, 2024
Nov 29, 2023
May 31, 2023
May 31, 2023
Jun 1, 2023
Jan 11, 2024
May 31, 2023
Dec 23, 2024
Oct 8, 2024
Jun 1, 2023
Feb 10, 2025
May 31, 2023
Jan 18, 2024
Jun 19, 2023
May 31, 2023
May 4, 2023

Using Sphinx

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.

Sphinx Extensions

Markdown Support

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.

Doxygen Integration

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.

CMake Integration

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.

Todo Items

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

PDF

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