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:
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:
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