Contributing to ROCm Docs#
6 min read time
AMD values and encourages the ROCm community to contribute to our code and documentation. This repository is focused on ROCm documentation and this contribution guide describes the recommended method for creating and modifying our documentation.
While interacting with ROCm Documentation, we encourage you to be polite and respectful in your contributions, content or otherwise. Authors, maintainers of these docs act on good intentions and to the best of their knowledge. Keep that in mind while you engage. Should you have issues with contributing itself, refer to discussions on the GitHub repository.
For additional information on documentation functionalities, see the user and developer guides for rocm-docs-core at rocm-docs-core documentation.
Our documentation includes both Markdown and RST files. Markdown is encouraged over RST due to the lower barrier to participation. GitHub-flavored Markdown is preferred for all submissions as it renders accurately on our GitHub repositories. For existing documentation, MyST Markdown is used to implement certain features unsupported in GitHub Markdown. This is not encouraged for new documentation. AMD will transition to stricter use of GitHub-flavored Markdown with a few caveats. ROCm documentation also uses Sphinx Design in our Markdown and RST files. We also use Breathe syntax for Doxygen documentation in our Markdown files. See GitHub’s guide on writing and formatting on GitHub as a starting point.
ROCm documentation adds additional requirements to Markdown and RST based files as follows:
Filenames and folder structure#
Please use snake case (all lower case letters and underscores instead of spaces)
for file names. For example,
Our documentation follows Pitchfork for folder structure.
All documentation is in
/docs except for special files like
the contributing guide in the
/ folder. All images used in the documentation are
placed in the
Language and Style#
Adopt Microsoft CPP-Docs guidelines for Voice and Tone.
ROCm documentation templates to be made public shortly. ROCm templates dictate the recommended structure and flow of the documentation. Guidelines on how to integrate figures, equations, and tables are all based off MyST.
Font size and selection, page layout, white space control, and other formatting
details are controlled via rocm-docs-core.
Raise issues in
rocm-docs-core for any formatting concerns and changes requested.