Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 1 | Documentation Guide |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 2 | ******************* |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 3 | |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 4 | Overview |
| 5 | ======== |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 6 | |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 7 | 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. |
| 8 | Here we're going to explain how to make modifications to this documentation. |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 9 | |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 10 | .. tip:: |
| 11 | The review workflow is almost identical to ONOS. |
| 12 | Please check `Sample Gerrit Workflow <https://wiki.onosproject.org/display/ONOS/Sample+Gerrit+Workflow>`_ if you are not yet familiar with the review workflow. |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 13 | |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 14 | |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 15 | Downloading Docs |
| 16 | ================ |
| 17 | |
| 18 | .. code-block:: console |
| 19 | |
| 20 | $ git clone ssh://<username>@gerrit.onosproject.org:29418/trellis-docs |
| 21 | |
| 22 | ``<username>`` should be replaced with your Gerrit username. |
| 23 | |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 24 | |
| 25 | Writing Docs |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 26 | ============ |
Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 27 | |
| 28 | Docs are generated using Sphinx: http://www.sphinx-doc.org |
| 29 | |
| 30 | Documentation is done in `reStructuredText |
| 31 | <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__ |
| 32 | (``.rst``) or the `CommonMark flavor of Markdown |
| 33 | <https://spec.commonmark.org/>`__ (``.md``), but only .rst files can use certain |
| 34 | features like embedded diagrams or tables. |
| 35 | |
| 36 | One tool that is useful for converting between text formats is `Pandoc |
| 37 | <https://pandoc.org>`__ - for example, to convert a ``.html`` file to ``.rst``, |
| 38 | you can run ``pandoc file.html -o file.rst``. |
| 39 | |
| 40 | Creating Diagrams |
| 41 | ----------------- |
| 42 | |
| 43 | The blockdiag suite of tools can be used for inline diagramming in ``.rst`` |
| 44 | files: |
| 45 | |
| 46 | - Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html |
| 47 | - Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html |
| 48 | |
| 49 | Attributes that can be applied to nodes: |
| 50 | http://blockdiag.com/en/blockdiag/attributes/node.attributes.html |
| 51 | |
| 52 | Examples: |
| 53 | |
| 54 | - blockdiag: http://blockdiag.com/en/blockdiag/examples.html |
| 55 | - nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html |
| 56 | - rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html |
Charles Chan | 3487b4a | 2019-09-23 11:16:10 -0700 | [diff] [blame] | 57 | |
| 58 | |
| 59 | Building Docs |
| 60 | ============= |
| 61 | |
| 62 | The documentation build process is stored in the Makefile. Building docs |
| 63 | requires Python to be installed, and most steps will create a virtualenv |
| 64 | (``doc_venv``) which install the documentation generation toolset. |
| 65 | |
| 66 | Run ``make html`` to generate html documentation in ``_build/html``. |
| 67 | |
| 68 | Run ``make reload`` to get a live reload in your browser (refreshes on document |
| 69 | save). |
| 70 | |
| 71 | To check the formatting of documentation, run ``make test``. This will be done |
| 72 | in Jenkins to validate the documentation, so please do this before you create a |
| 73 | patchset. |
| 74 | |
| 75 | |
| 76 | Submitting a Review |
| 77 | =================== |
| 78 | |
| 79 | **Make sure you build and test the changes**. |
| 80 | Once done, you can submit a review by running the following commands: |
| 81 | |
| 82 | .. code-block:: console |
| 83 | |
| 84 | $ git add . |
| 85 | $ git commit -m '<commit message>' |
| 86 | $ git review |