About ROCm Documentation#
5 min read time
ROCm documentation is made available under open source licenses. Documentation is built using open source toolchains. Contributions to our documentation is encouraged and welcome. As a contributor, please familiarize yourself with our documentation toolchain.
ReadTheDocs is our front end for the our documentation. By front end, this is the tool that serves our HTML based documentation to our end users.
Doxygen is the most common inline code documentation standard. ROCm projects are use Doxygen for public API documentation (unless the upstream project is using a different tool).
Sphinx is a documentation generator originally used for python. It is now widely used in the Open Source community. Originally, sphinx supported RST based documentation. Markdown support is now available. ROCm documentation plans to default to markdown for new projects. Existing projects using RST are under no obligation to convert to markdown. New projects that believe markdown is not suitable should contact the documentation team prior to selecting RST.
Markedly Structured Text (MyST) is an extended
flavor of Markdown (CommonMark) influenced by reStructuredText (RST) and Sphinx.
It is integrated via
A cheat sheet that showcases how to use the MyST syntax is available over at the Jupyter
ROCm is using the Sphinx Book Theme. This theme is used by Jupyter books. ROCm documentation applies some customization include a header and footer on top of the Sphinx Book Theme. A future custom ROCm theme will be part of our documentation goals.
Sphinx Design is an extension for sphinx based websites that add design functionality. Please see the documentation here. ROCm documentation uses sphinx design for grids, cards, and synchronized tabs. Other features may be used in the future.
Sphinx External TOC#
ROCm uses the
for our navigation. This tool allows a YAML file based left navigation menu. This
tool was selected due to its flexibility that allows scripts to operate on the
YAML file. Please transition to this file for the project’s navigation. You can
_toc.yml.in file in this repository in the docs/sphinx folder for an
Sphinx uses Breathe to integrate Doxygen content.
rocm-docs-core pip package#
rocm-docs-core is an AMD maintained project that applies customization for our documentation. This project is the tool most ROCm repositories will use as part of the documentation build.