readme.rst

Documentation Guide
===================

Building the Docs
------------------

The documentation build process is stored in the Makefile. Building docs
requires Python to be installed, and most steps will create a virtualenv
(``doc_venv``) which install the documentation generation toolset.

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

Run ``make reload`` to get a live reload in your browser (refreshes on document
save).

To check the formatting of documentation, run ``make lint``. This will be done
in Jenkins to validate the documentation, so please do this before you create a
patchset.

Writing Docs
------------

Docs are generated using Sphinx: http://www.sphinx-doc.org

Documentation is done in `reStructuredText
<http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__
(``.rst``)  or the `CommonMark flavor of Markdown
<https://spec.commonmark.org/>`__ (``.md``), but only .rst files can use certain
features like embedded diagrams or tables.

One tool that is useful for converting between text formats is `Pandoc
<https://pandoc.org>`__ - for example, to convert a ``.html`` file to ``.rst``,
you can run ``pandoc file.html -o file.rst``.

Creating Diagrams
-----------------

The blockdiag suite of tools can be used for inline diagramming in ``.rst``
files:

- Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html
- Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html

Attributes that can be applied to nodes:
http://blockdiag.com/en/blockdiag/attributes/node.attributes.html

Examples:

- blockdiag: http://blockdiag.com/en/blockdiag/examples.html
- nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html
- rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html