Written content formatting reference#

Adding targets#

Adding custom targets or anchors to the headings is really helpful for cross-referencing. They allow us to link to the heading using a simple syntax. They are defined using this syntax:

.. _mytarget:
(mytarget)=

They are referred using this syntax:

:ref:`mytarget`
{ref}`mytarget`

For adding anchors in .ipynb files, Markdown syntax will be used in the markdown cells of .ipynb files.

See also

Cross-referencing arbitrary locations Sphinx documentation about the ref role.

Hyperlink targets Docutils documentation on targets (another name for anchors) with extensive detail on how and when they can be used.

MyST targets and cross-referencing docs

Backticks for highlighting code keywords#

For highlighting inline code keywords or file names, backticks are used. In Markdown single backticks are used while in rST double backticks are used. For example, for highlighting the file name conf.py, we will use this syntax:

``conf.py``
`conf.py`

Table of content tree#

All documentation generated with sphinx is structured via toctrees. Sphinx prints a warning if a file is not part of any toctree unless that file is marked as an orphan.

The hierarchy defined via toctrees (and not the file hierarchy!) is the one that defines the nabvar and the contents of the left sidebar. Keeping the toctrees organized and up to date ensures the sphinx build works, that the generated documentation is correctly ordered and can be navigated and that all pages can be reached. It also enables navigation to the Previous and Next pages in the footer.

Follow this syntax for adding the table of content:

.. toctree::
    developer_guide
    doc_guide
:::{toctree}
developer_guide
doc_guide
:::

Read more about the Sphinx toctree directive.

Adding references#

In ArviZ docs, we use intersphinx_mapping to add references to other libraries functions and objects. The intersphinx ensures us that cross-references to the target project exist. It is the only way to link for multiversioned docs to link to themselves. It raises a warning if the target references are changed or removed. This way we don’t need to add the long exact links. It saves a lot of time and effort.

Code tabs#

You will find code tabs on every other page in ArviZ docs. As we have two main types of files, i.e, .rst and .md, we often use two code tabs to show the functionalities in both rST and Markdown.

Synchronised Tabs#

ArviZ docs are using sphinx-design extension for adding sync code tabs in conf.py. You can check the syntax and more info about it at Synchronised Tabs. Using this extension saves us from a lot of raw-html code. Sphinx provides this extension to make our work easy and or code more concise.

Extensions#

Sphinx supports a lot of extensions to improve and customize the doc features. ArviZ makes use of these builtin and external extensions to add extra roles. See the Extensions in ArviZ.