CUDA Quantum Documentation

This folder contains tools and content to build the CUDA Quantum documentation. The script for building docs can be used to build the complete CUDA Quantum documentation. Please see the comment in that script for more detail.

We use Sphinx to produce documentation in HTML format. This documentation includes conceptual documentation in the form of Markdown or reStructuredText format, API documentation generated based on doc comments in the source code, as well as potentially source code examples and snippets. Unfortunately, syntax highlighting for MLIR code snippets is currently not available in Pygments.

API Documentation

We use Sphinx to include documentation defined in the form of doc comments in the source code for all of our APIs. The build is configured by the settings in the sphinx/conf.py file.

• C++ source code:
  As part of the build Doxygen is used to generated documentation based on doc comments. The documentation generation is configured in the Doxyfile.in file - see the manual for possible configurations. Our build replaces the environment variables used in that file to produce the final Doxyfile with which doxygen is invoked. We use the Breathe extension for Sphinx to incorporate content from the generated XML files in our docs.

• TableGen files:
  Our CMake files define the cudaq-doc target that produces Markdown files containing documentation for TableGen files. We use the MyST-Parser extension for Sphinx to incorporate content from the generated Markdown files in our docs.

• Python bindings:
  We use pybind11 to define Python bindings for the CUDA Quantum API. Doc comments are defined as part of defining these bindings in C++. To incorporate the API documentation, the cudaq Python package needs to be built and installed prior to generating the CUDA Quantum documentation. The build_docs.sh script will automatically do that if necessary. We use the AutoDoc extension for Sphinx to incorporate Python documentation.

Sphinx Extensions

The extensions we use to generate API docs are outlined and linked in the section above. The full list of built-in Sphinx tensions can be found here. The list of extensions that are enabled for building CUDA Quantum documentation is defined by the value of the extensions configuration in conf.py.

References

Additional links that may be helpful that are not listed above:

• References and automatic link generation in Doxygen
• Using Napoleon style for Python doc comments
• Cross-referencing Python objects
• Cross-referencing C++ objects
• Sphinx configuration options
• Syntax highlighting in inline code
• Test examples in Python documentation