Documentation Guide

Overview

Trellis documentation is hosted on Gerrit 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 if you are not yet familiar with the review workflow.

Downloading Docs

$ 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 (.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 files:

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

Examples:

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:

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