Documentation structure

Documentation structure#

Applies to Linux and Windows

2024-03-04

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.

Contents