Written content formatting reference#
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:
They are referred using this syntax:
For adding anchors in
.ipynb files, Markdown syntax will be used in the markdown cells of
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:
Table of content tree#
All documentation generated with sphinx is structured via
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:
Read more about the Sphinx toctree directive.
In ArviZ docs, we use
intersphinx_mapping to add references to other libraries functions and objects.
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.
You will find code tabs on every other page in ArviZ docs. As we have two main types of files, i.e,
.md, we often use two code tabs to show the functionalities in both rST and Markdown.
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.
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.