About ROCm Documentation#
6 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.
rocm-docs-core is an AMD-maintained project that applies customization for our documentation. This project is the tool most ROCm repositories use as part of the documentation build. It is also available as a pip package on PyPI.
See the user and developer guides for rocm-docs-core at rocm-docs-core documentation.
Sphinx is a documentation generator originally used for Python. It is now widely used in the Open Source community. Originally, Sphinx supported reStructuredText (RST) based documentation, but 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.
Read the Docs#
Read the Docs is the service that builds and hosts the HTML documentation generated using Sphinx to our end users.
Doxygen is a documentation generator that extracts information from inline code. ROCm projects typically use Doxygen for public API documentation unless the upstream project uses a different tool.
Breathe is a Sphinx plugin to integrate Doxygen content.
Markedly Structured Text (MyST) is an extended
flavor of Markdown (CommonMark) influenced by reStructuredText (RST) and Sphinx.
It is integrated into ROCm documentation by the Sphinx extension
A cheat sheet that showcases how to use the MyST syntax is available over at
the Jupyter reference.
Sphinx External TOC#
Sphinx External Table of Contents (TOC)
is a Sphinx extension used for ROCm documentation navigation. This tool generates a navigation menu on the left
based on a YAML file that specifies the table of contents.
It 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 Book Theme#
Sphinx Book Theme is a Sphinx theme that defines the base appearance for ROCm documentation. ROCm documentation applies some customization, such as a custom header and footer on top of the Sphinx Book Theme.
Sphinx Design is a Sphinx extension that adds design functionality. ROCm documentation uses Sphinx Design for grids, cards, and synchronized tabs.