docs/sphinx.rst

Sphinx
======

Docs are generated using :doc:`Sphinx <sphinx:usage/index>` using the
:doc:`reStructuredText <sphinx:usage/restructuredtext/basics>` syntax.

Sphinx was chosen because it's widely used (Python official docs, Linux Kernel,
Read the Docs, etc.), open source, actively maintained, has code highlighting,
and a good client-side search implementation.

Writing Documentation
---------------------

reStructuredText syntax references can be found here:

* :doc:`Sphinx reStructuredText Primer <sphinx:usage/restructuredtext/basics>`
* `rst cheat sheet <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>`_

rST creates headings by underlining the heading with a series of symbol
characters. There is no specific required order for these, but for consistency
most ONF docs use the following symbols/order to represent heading levels::

   H1: =
   H2: -
   H3: "
   H4: '
   H5: ^
   H6: +

Linking within Documentation
""""""""""""""""""""""""""""


Referencing other Documentation
"""""""""""""""""""""""""""""""

Other Sphinx-built documentation, both ONF and non-ONF can be linked to using
:doc:`InterSphinx <sphinx:usage/extensions/intersphinx>`, which allows you to
create links that will work even if the other site moves or reorganizes
content.

New InterSphinx reference requires modifying the ``intersphinx_mapping``
variables of the ``conf.py`` file.

You can see all link targets available on a remote Sphinx's docs by running::

  python -msphinx.ext.intersphinx http://otherdocs/objects.inv

More information about InterSphinx:

* :doc:`Read the Docs InterSphinx Guide <rtd:guides/intersphinx>`

Adding Images and Diagrams
""""""""""""""""""""""""""

There are multiple ways to add images and diagrams to the documentation.

Generally, you should prefer using `SVG
<https://en.wikipedia.org/wiki/Scalable_Vector_Graphics>`_ images, as these can
be scaled to any size without quality loss.

If you're creating diagrams, there are multiple tools available.
:doc:`Graphviz <sphinx:usage/extensions/graphviz>` can render inline text-based
graphs definitions and diagrams within the documentation, and is best choice for
simple diagrams.

More complex diagrams can be created in `Diagrams.net/Draw.io
<https://www.diagrams.net/>`_ format, which is available as a standalone app,
web app, or integrated with various other tools like Google Workspace. When
saving these diagrams, use the SVG format, and check the **Include a copy of my
diagram** box. This will let someone open the SVG later within Diagrams.net
from file saved in the documentation and edit it without any loss in
functionality or quality.

The last resort is to use raster (bitmap) images. If they're drawings or screen
captures, use the `PNG
<https://en.wikipedia.org/wiki/Portable_Network_Graphics>`_ format.  Consider
optimizing the PNG files with a tool like `OptiPNG
<http://optipng.sourceforge.net/>`_, or `pngquant <https://pngquant.org/>`_ to
save space and data transfer required.

If you need to include a photograph, use `JPEG
<https://en.wikipedia.org/wiki/JPEG>`_.

Building the Documentation
--------------------------

The documentation build process is stored in a ``Makefile``. Building docs
requires Python to be installed, and most steps will create a virtualenv
(usually ``venv-docs``) which contains the required tools.  You may also need
to install the ``enchant`` C library using your system's package manager for
the spelling checker to function properly.

Run ``make html`` to generate html documentation in ``_build/html``.

There is also a test target, ``make test``, which will run all the following
checks - this is what Jenkins does on patchset validation, so:

* ``make lint``: Check the formatting of documentation using `doc8
  <https://github.com/PyCQA/doc8>`_.

* ``make license``: Verifies licensing is correct using :ref:`REUSE
  <policies/licensing:REUSE License Tool>`

* ``make spelling``: Checks spelling on all documentation. If there are
  additional words that are correctly spelled but not in the dictionary
  (acronyms, nouns, etc.) please add them to the ``dict.txt`` file, which
  should be alphabetized using ``sort``

* ``make linkcheck``: Verifies that links in the document are working and
  accessible, using Sphinx's built in linkcheck tool. If there are links that
  don't work with this, please see the ``linkcheck_ignore`` section of
  ``conf.py``.

Some sites may have the ability to build a PDF file of the documentation using
``make latexpdf``. This requires that you have a recent LaTeX installation and
``latexmk`` installed.

Versioning Documentation
""""""""""""""""""""""""

To change the version shown on the built site, change the contents of the
``VERSION`` file to be released SemVer version. This will create a tag on the
repo.

Then when ``make multiversion`` target can be used which will build all
versions tagged or branched on the remote to ``_build/multiversion``. This will
use a fork of `sphinx-multiversion
<https://github.com/Holzhaus/sphinx-multiversion>`_ to build multiple versions
and a menu on the site.

There are variables in ``conf.py`` to determine which tags/branches to build.