documentation.rst

Documentation Guide
*******************

Overview
========

Trellis documentation is hosted on `Gerrit <https://gerrit.onosproject.org/admin/projects/trellis-docs>`_ and published automatically to https://docs.trellisfabric.org whenever there is a patch being merged.
Here we're going to explain how to make modifications to this documentation.

.. tip::
    The review workflow is almost identical to ONOS.
    Please check `Sample Gerrit Workflow <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_ if you are not yet familiar with the review workflow.


Downloading Docs
================

.. code-block:: console

    $ git clone ssh://<username>@gerrit.onosproject.org:29418/trellis-docs

``<username>`` should be replaced with your Gerrit username.


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


Building 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 test``. This will be done
in Jenkins to validate the documentation, so please do this before you create a
patchset.


Submitting a Review
===================

**Make sure you build and test the changes**.
Once done, you can submit a review by running the following commands:

.. code-block:: console

    $ git add .
    $ git commit -m '<commit message>'
    $ git review