CUDA-QX Documentation

This folder contains tools and content to build the CUDA-QX documentation. The script for building docs can be used to build the complete CUDA-QX 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.

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.

• Python bindings:
  We use pybind11 to define Python bindings for the CUDA-QX API. Doc comments are defined as part of defining these bindings in C++. To incorporate the API documentation, the cudaqx Python package needs to be built and installed prior to generating the CUDA-QX documentation. This project generates ReStructuredText documentation from Python docstrings using autodoc. The generated .rst files are in docs/source/apidoc. The files are generated automatically by doc-build and doc-clean will remove them.

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