Documentation guidelines

The documentation is written in reStructuredText (reST) and built with Sphinx and Doctools for HTML and PDF output. For installation and build commands, see Installing and Command line interface.

Sections marked sphinx work in any Sphinx documentation. Sections marked doctools require adi_doctools. See Custom roles and Custom directives for all Doctools roles and directives, and Advanced configuration for configuration and extension development.

For the full core reference, see Sphinx’s Roles and Directives, and the reST primer.

Writing a page

A .rst file is a reStructuredText document. In Sphinx, its source path without the extension is its document name (docname): user-guide/setup.rst becomes user-guide/setup. Document names are used in links and navigation.

A page has a title, paragraphs, and sections, for example:

.. _board-setup:

Board setup
===========

Connect and configure the evaluation board.

Prerequisites
-------------

* A USB cable.
* The board's power supply.

Procedure
---------

#. Connect the cable.
#. Apply power.

Headings

Headings are marked by repeated characters. By convention, = is used for titles and - for subtitles. The underline must be at least as long as the source heading. A heading creates a section and appears in the page’s table of contents; rubric creates a visual heading without a section.

Roles and directives

A role applies to inline text: :kbd:`Control-C` marks a keyboard shortcut, and :ref:`board-setup` creates a cross-reference. A directive introduces a block, with this structure:

.. code-block:: python
   :caption: Read a sample

   sample = read_adc()
   print(sample)

Here code-block is the directive, python is its argument, caption is an option, and the indented code is its content. The available arguments, options, and content depend on the directive. Doctools adds the roles and directives listed at Custom roles and Custom directives.

Indentation and blank lines

Indent directive options and content by three spaces. For lists, align continuation paragraphs and nested blocks with the first character of the item’s text: two spaces for *, three for #.. Keep a blank line before the content of a directive, between block elements, and after a nested block before returning to the outer indentation:

#. Configure the device.

   * Select the interface.
   * Set the sample rate:

     .. code-block:: bash
        :caption: Set the sample rate to 1 MSPS

        iio_attr -c ad4052 voltage0 sampling_frequency 1000000

Source line width

Wrap text to fewer than 80 columns, but keep URLs and reference roles on one line. Preserve the language’s own indentation inside code blocks, offset by the directive’s three spaces.

For neovim, you can visually select the block with Ctrl+V, then wrap with gq.

For vscode, you can install Rewrap, select the block and wrap with Alt+Q.

As a last resort, you can use the fold command to break the lines of imported text while respecting word-breaks:

fold -sw 80 imported.txt > imported.rst

Do not apply it to reST directives, tables, or code.

Inline markup and roles sphinx

reST provides *italic*, **bold**, and double backticks for inline code. Sphinx adds the following inline roles:

Common inline roles

Use

Source

Result

Command

:command:`make`

make

Program

:program:`python`

python

Path with a variable part

:file:`/sys/{device}/config`

/sys/device/config

Replaceable command argument

:samp:`adoc serve -p {port}`

adoc serve -p port

Keyboard shortcut

:kbd:`Control-C`

Control-C

UI label

:guilabel:`Apply`

Apply

Menu path

:menuselection:`File --> Open`

File ‣ Open

Abbreviation

:abbr:`ADC (analog-to-digital converter)`

ADC

Inline code

:code:`value = 1`

value = 1

Inline mathematics

:math:`f_s = 1/T`

\(f_s = 1/T\)

Other roles include dfn for defining a term, regexp for a regular expression, makevar for a Make variable, manpage for a manual page, and mimetype or mailheader for protocol text. pep, rfc, cve, and cwe link to standards and security entries.

Inline code is not syntax-highlighted by default. Define a language role when needed:

.. role:: python(code)
   :language: python

Use :python:`len(samples)` to count samples.

The substitutions |version|, |release|, and |today| come from Sphinx configuration. Use version for the short version and release for the full release string.

Lists sphinx

Unordered lists use * or - and ordered lists #..

Child items must be aligned with the first letter of the parent item; that means, 2 spaces for unordered lists and 3 spaces for ordered lists, for example:

#. Parent ordered item.

   * Child unordered item.

     #. Child ordered item.
     #. Child ordered item.

Renders as:

  1. Parent numbered item.

    • Child unordered item.

      1. Child ordered item.

      2. Child ordered item.

Code sphinx

Prefer code-block to code directives, because code-blocks have more options, such as showing line numbers and emphasizing lines.

For example,

.. code-block:: python
   :linenos:
   :emphasize-lines: 2

   def hello_world():
       string = "Hello world"
       print(string)

Renders as:

1def hello_world():
2    string = "Hello world"
3    print(string)

Preserve the original code indentation, just offset it by 3 spaces.

Use literalinclude to display code directly from a source file:

.. literalinclude:: examples/capture.py
   :language: python
   :caption: Capture samples
   :lines: 10-25

The path is relative to the document. For interactive command sessions with prompts and output, see Doctools’ Shell.

Admonitions sphinx

Admonitions mark notes, tips, warnings, and other information:

.. warning::

   Disconnect power before changing the jumpers.

.. admonition:: Before you start

   Check the board revision.

.. seealso::

   :ref:`Installation <install>`

Version history sphinx

These directives record when a feature was added, changed, deprecated, or removed. For deprecations and removals, name the replacement:

.. version-added:: 1.23
   Added streaming capture.

.. version-changed:: 1.24
   Capture now returns timestamps.

.. version-deprecated:: 1.25
   Use streaming capture instead of polling.

.. version-removed:: 2.0
   Polling was removed; use streaming capture.

See Sphinx’s version-added for details.

Images sphinx

For real photos, use the figure directive. It enables a link to open the image (or click-to-zoom with JavaScript enabled). For PDF LaTeX builds, it also properly aligns the figure in the page without relying on the image width.

Use image for logos, symbols, and instances where you don’t want the image resized. Provide alternative text for both. For example:

.. figure:: schematic.svg
   :alt: ADC connected to the controller over SPI
   :width: 80%
   :name: adc-connections

   Connections between the ADC and controller.

For diagrams, or any vector, prefer the SVG format for images, and save it as Optimized SVG in Inkscape to use less space.

Store them in a hierarchy; do not use images subdirectories. The idea is to have simpler relative paths, for example:

.. image:: ad2234_sdz_schematic.svg

Or even simpler schematic.svg, if already in an ad2234 directory.

Instead of overcomplicated paths like:

.. image:: ../../project/images/ad2234_sdz/ad2234_sdz_schematic.svg

In general, this avoids dangling artifacts and keeps the documentation simple.

The following image classes are provided by Doctools:

  • no-background removes the default white image background in dark mode.

  • only-light and only-dark select theme-specific assets.

  • only-print and only-screen select print versus screen presentation.

Set them with the directive’s class option:

.. image:: logo.svg
   :alt: Project logo
   :class: no-background

.. image:: screenshot-light.png
   :alt: Capture window in the light theme
   :class: only-light

.. image:: screenshot-dark.png
   :alt: Capture window in the dark theme
   :class: only-dark

For Git LFS setup, see Git Large File Storage. Git LFS integration describes how local previews fetch LFS-backed images.

Reusing content sphinx

Use include to insert shared reST at a specific location. Unlike toctree, it makes the included text part of the current document rather than linking to a separate page:

.. include:: ../common/support.rst

The path is relative to the including file. The included headings must fit the surrounding hierarchy, and any labels must remain unique in the build. Do not add an include-only fragment to a toctree as well. See Shared HDL sections for the shared HDL support and information sections.

Use literalinclude for displaying a file’s source without parsing it, and download to offer the file itself:

:download:`Download the sample data <sample/fruits.csv>`

Math sphinx

Use math for a displayed equation and math inline. A labeled math block can be referenced with :eq:`label`:

.. math::
   :label: sample-period

   T = \frac{1}{f_s}

The sample period follows :eq:`sample-period`.

Tables sphinx

Prefer list tables and imported CSV tables (using the file option), because they are faster to create, easier to maintain, and the 80 column-width rule can be respected with list tables.

Only use Grid Tables if strictly necessary, since they are hard to update.

For side-by-side links or content, use cards and grids rather than tables.

List tables

Prefer list-table for hand-maintained data. Each outer item is a row; each inner item is a cell. Every row must contain the same number of cells. header-rows identifies column headers, stub-columns identifies row headers, and widths sets relative column widths:

.. list-table:: Fruits
   :name: fruit-table
   :header-rows: 1
   :stub-columns: 1
   :widths: 25 75

   * - Fruit
     - Color
   * - Papaya
     - Orange inside, green to yellow outside.
   * - Rambutan
     - Red, with soft spines.
Fruits

Fruit

Color

Papaya

Orange inside, green to yellow outside.

Rambutan

Red, with soft spines.

Cells can contain inline roles, references, paragraphs, and lists; indent nested content under the cell’s text. A list table cannot span cells.

CSV tables

Use csv-table for imported or generated data. file is relative to the source document; header-rows: 1 uses the file’s first row as headings:

.. csv-table:: Fruits from a file
   :file: sample/fruits.csv
   :header-rows: 1
   :widths: 25 75
Fruits from a file

Fruit

Color

Papaya

Orange, yellow

Rambutan

Red

Guava

Green

Download the CSV. For inline CSV, use header to supply column names separately:

.. csv-table:: Fruits
   :header: "Fruit", "Color"

   "Papaya", "Orange, yellow"
   "Rambutan", "Red"

Quote cells containing commas and double embedded quotation marks according to CSV rules. Options such as delim and encoding handle other inputs.

Simple and grid tables

Simple tables work for short text. Blank lines separate multiline rows; empty first-column cells need special care. Use list tables for longer content:

========  ==============
Fruit     Color
========  ==============
Papaya    Orange, yellow
Rambutan  Red
========  ==============

Grid tables support multiline cells and row/column spans. The = border separates the header from the body. Use table to add a caption, name, and widths:

.. table:: Fruits
   :name: grid-fruits
   :widths: 25 75

   +----------+----------------+
   | Fruit    | Color          |
   +==========+================+
   | Papaya   | Orange, yellow |
   +----------+----------------+
   | Rambutan | Red            |
   +----------+----------------+

See Grid tables for the full syntax.

HTML, PDF, and long tables

  • Give tables a caption and a header row; do not simulate headers with bold text alone. Use name and numref when numbering is enabled.

  • Relative widths do not guarantee identical HTML and PDF wrapping.

  • For multipage PDF tables, add :class: longtable. Sphinx’s tabularcolumns sets LaTeX column specifications for the next table; it does not control HTML widths.

  • A table row cannot span PDF pages. Split rows that are too tall to fit.

  • Do not use raw:: html tables for normal documentation: they disappear from PDF and text output.

For example, a LaTeX-specific width override for an imported long table is:

.. tabularcolumns:: |p{2cm}|p{9cm}|

.. csv-table:: Fruit catalog
   :file: sample/fruits.csv
   :header-rows: 1
   :widths: 20 80
   :class: longtable

To tune styling, the following classes are available:

  • bold-header: Make the header bold.

  • bold-first-column: Make the first column bold.

Grids, card, flex, tabs, collapsible doctools

Use Grid, Card, Flex, Tabs, Collapsible to organize content. For example using cards:

.. grid::
   :columns: 2

   .. card:: Custom roles
      :ref: role

      Links, colors, and badges.

   .. card:: Custom directives
      :ref: directive

      Layout, shell sessions, and media.

Renders as:

External references sphinx

Intersphinx resolves references to other Sphinx builds. Each configured build supplies an objects.inv inventory of its labels, pages, and other reference targets. The inventory name selects which documentation to search:

:external+hdl:ref:`spi_engine control-interface`
:external+hdl:ref:`Control interface <spi_engine control-interface>`

These are the external equivalents of local ref links. Other reference types, such as term, envvar, and numref, can also use inventories. Check build warnings for unresolved targets. To inspect the labels and document names available in an inventory:

python3 -m sphinx.ext.intersphinx \
  https://analogdevicesinc.github.io/hdl/objects.inv

Use the explicit external+inventory form rather than the older ref-inventory shorthand. Sphinx 8 also accepts inventory-qualified targets such as :ref:`hdl:label`, allowing local references to take precedence. Use the explicit form for repositories that still need Sphinx 7; adoc adapts references when assembling custom documents.

In-organization references doctools

Doctools configures inventories for organization repositories through interref_repos in conf.py:

interref_repos = ['hdl', 'no-OS', 'pyadi-iio/main']

A suffix such as /main selects a build below that repository’s root. For example, pyadi-iio/main selects its main/ documentation. Use the same mechanism for a published version such as /v1.1; see Versioned.

The base URL defaults to https://analogdevicesinc.github.io/. Override it with interref_uri in conf.py or the ADOC_INTERREF_URI environment variable; a local path such as ../../ can also be used.

With interref_local = True, Doctools additionally looks for local documentation alongside the current repository, for example:

/data/work
├── my-repo-0/doc/sources
├── my-repo-1/docs
└── my-repo-2/doc

Repository source paths are resolved through adi_doctools/lut.py. For private inventories and authentication, see Private repositories. For a target with a different URL layout, configure an explicit mapping as described below.

Third-party references sphinx

Enable sphinx.ext.intersphinx in extensions and add an entry to intersphinx_mapping in conf.py. Each entry pairs an inventory name with the documentation base URL and the inventory location; None uses objects.inv under that URL:

intersphinx_mapping = {
    'sphinx': ('https://www.sphinx-doc.org/en/master', None),
}

For example, this mapping makes :external+sphinx:ref:`rst-primer` available. The same mechanism works for an organization repository with a custom URL or a build not covered by interref_repos.

Before publishing

  • Preview with Serve and fix build warnings, including missing references, invalid syntax, and unlisted pages.

  • Check that example commands work, and that images have alt text.

  • Use only (e.g. only:: html or only:: latex) only when the HTML and PDF really need different content.

  • Extension setup, custom JavaScript, version configuration, wiki imports, and repository-specific quirks are described in Advanced configuration.

Reference and advanced guide

The following sections describe Doctools custom tools and advanced usage: