Sphinx ====== Docs are generated using :doc:`Sphinx ` using the :doc:`reStructuredText ` 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 ` * `rst cheat sheet `_ 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 `, 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 ` Adding Images and Diagrams """""""""""""""""""""""""" There are multiple ways to add images and diagrams to the documentation. Generally, you should prefer using `SVG `_ images, as these can be scaled to any size without quality loss. If you're creating diagrams, there are multiple tools available. :doc:`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 `_ 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 `_ format. Consider optimizing the PNG files with a tool like `OptiPNG `_, or `pngquant `_ to save space and data transfer required. If you need to include a photograph, use `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 `_. * ``make license``: Verifies licensing is correct using :ref:`REUSE ` * ``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 `_ to build multiple versions and a menu on the site. There are variables in ``conf.py`` to determine which tags/branches to build.