blob: c067956ff96a8de27901e9c4f13258eeda962a53 [file] [log] [blame]
Documentation Guide
Trellis documentation is hosted on `Gerrit <>`_ and published automatically to 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 <>`_ if you are not yet familiar with the review workflow.
Downloading Docs
.. code-block:: console
$ git clone ssh://<username>
``<username>`` should be replaced with your Gerrit username.
Writing Docs
Docs are generated using Sphinx:
Documentation is done in `reStructuredText
(``.rst``) or the `CommonMark flavor of Markdown
<>`__ (``.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
<>`__ - 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``
- Block diagrams:
- Network diagrams (& racks):
Attributes that can be applied to nodes:
- blockdiag:
- nwdiag:
- rackdiag:
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
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
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