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