Documentation structure#
2024-04-25
5 min read time
Our documentation follows the Pitchfork folder structure. Most documentation files are stored in the
/docs
folder. Some special files (such as release, contributing, and changelog) are stored in the root
(/
) folder.
All images are stored in the /docs/data
folder. An image’s file path mirrors that of the documentation
file where it is used.
Our naming structure uses kebab case; for example, my-file-name.rst
.
Supported formats and syntax#
Our documentation includes both Markdown and RST files. We are gradually transitioning existing Markdown to RST in order to more effectively meet our documentation needs. When contributing, RST is preferred; if you must use Markdown, use GitHub-flavored Markdown.
We use Sphinx Design syntax and compile our API references using Doxygen.
The following table shows some common documentation components and the syntax convention we use for each:
Component | RST syntax |
---|---|
Code blocks |
.. code-block:: language-name
My code block.
|
Cross-referencing internal files |
:doc:`Title <../path/to/file/filename>`
|
External links |
`link name <URL>`_
|
Headings |
******************
Chapter title (H1)
******************
Section title (H2)
===============
Subsection title (H3)
---------------------
Sub-subsection title (H4)
^^^^^^^^^^^^^^^^^^^^
|
Images |
.. image:: image1.png
|
Internal links |
1. Add a tag to the section you want to reference:
.. _my-section-tag: section-1
Section 1
==========
2. Link to your tag:
As shown in :ref:`section-1`.
|
Lists |
# Ordered (numbered) list item
* Unordered (bulleted) list item
|
Math (block) |
.. math::
A = \begin{pmatrix}
0.0 & 1.0 & 1.0 & 3.0 \\
4.0 & 5.0 & 6.0 & 7.0 \\
\end{pmatrix}
|
Math (inline) |
:math:`2 \times 2 `
|
Notes |
.. note::
My note here.
|
Tables |
.. csv-table:: Optional title here
:widths: 30, 70 #optional column widths
:header: "entry1 header", "entry2 header"
"entry1", "entry2"
|
Language and style#
We use the Google developer documentation style guide to guide our content.
Font size and type, page layout, white space control, and other formatting details are controlled via rocm-docs-core. If you want to notify us of any formatting issues, create a pull request in our rocm-docs-core GitHub repository.
Building our documentation#
To learn how to build our documentation, refer to Building documentation.