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.
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.
Hyperlinks#
Complementary functions such as arviz.compare()
and arviz.plot_compare()
should reference
each other in their docstrings using a hyperlink, not only by name. The same
should happen with external functions whose usage is assumed to be known; a
clear example of this situation are docstrings on kwargs
passed to bokeh or
matplotlib methods. This section covers how to reference functions from any
part of the docstring. Read more about it here.
Reference external libraries#
Sphinx is configured to ease referencing libraries ArviZ relies heavily on by using intersphinx. See guidance on the reference about how to link to objects from external libraries and the value of intersphinx_mapping in conf.py for the complete and up to date list of libraries that can be referenced.
In ArviZ docs, you can add references to functions and objects of matplotlib
, bokeh
, xarray
, etc following the simple syntax. Let’s try adding a function of few libraries, i.e., xarray.Dataset.sel()
, matplotlib.pyplot.subplots()
and
bokeh.plotting.figure()
.
:meth:`xarray.Dataset.sel`
:func:`matplotlib.pyplot.subplots`
:func:`bokeh.plotting.figure`
{meth}`xarray.Dataset.sel`
{func}`matplotlib.pyplot.subplots`
{func}`bokeh.plotting.figure`
Note that the :key:
before
the reference must match the kind of object that is being referenced, it
generally will not be :ref:
nor :doc:
. For
example, for functions :func:
has to be used and for class methods
:meth:
. The complete list of keys can be found here.
The extension sphobjinv can also be helpful in order to get the exact type and name of a reference. Below is an example on getting a reference from matplotlib docs:
$ sphobjinv suggest -t 90 -u https://matplotlib.org/objects.inv "axes.plot"
Remote inventory found.
:py:method:`matplotlib.axes.Axes.plot`
:py:method:`matplotlib.axes.Axes.plot_date`
:std:doc:`api/_as_gen/matplotlib.axes.Axes.plot`
:std:doc:`api/_as_gen/matplotlib.axes.Axes.plot_date`
We can therefore link to matplotlib docs on Axes.plot
from any docstring
using:
:meth:`mpl:matplotlib.axes.Axes.plot`
{meth}`mpl:matplotlib.axes.Axes.plot`
The intersphinx_mappings
defined for ArviZ can be seen in conf.py
.
Moreover, the intersphinx key is optional. Thus, the pattern to get sphinx to generate links is:
:type_id:`(intersphinx_key:)object_id`
{type_id}`(intersphinx_key:)object_id`
with the part between brackets being optional. See the docstring on
to_dataframe()
and
its source for an example.
Referencing ArviZ objects#
The same can be done to refer to ArviZ functions, in which case,
:func:`arviz.loo`
is enough, there is no need to use intersphinx.
Moreover, using :func:`~arviz.loo`
will only show loo
as link text
due to the preceding ~
.
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.