Zack Williams | 553a363 | 2019-08-09 17:14:43 -0700 | [diff] [blame] | 1 | Documentation Guide |
| 2 | =================== |
| 3 | |
| 4 | Building the Docs |
| 5 | ------------------ |
| 6 | |
| 7 | The documentation build process is stored in the Makefile. Building docs |
| 8 | requires Python to be installed, and most steps will create a virtualenv |
| 9 | (``doc_venv``) which install the documentation generation toolset. |
| 10 | |
| 11 | Run ``make html`` to generate html documentation in ``_build/html``. |
| 12 | |
| 13 | Run ``make reload`` to get a live reload in your browser (refreshes on document |
| 14 | save). |
| 15 | |
| 16 | To check the formatting of documentation, run ``make lint``. This will be done |
| 17 | in Jenkins to validate the documentation, so please do this before you create a |
| 18 | patchset. |
| 19 | |
| 20 | Writing Docs |
| 21 | ------------ |
| 22 | |
| 23 | Docs are generated using Sphinx: http://www.sphinx-doc.org |
| 24 | |
| 25 | Documentation is done in `reStructuredText |
| 26 | <http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`__ |
| 27 | (``.rst``) or the `CommonMark flavor of Markdown |
| 28 | <https://spec.commonmark.org/>`__ (``.md``), but only .rst files can use certain |
| 29 | features like embedded diagrams or tables. |
| 30 | |
| 31 | One tool that is useful for converting between text formats is `Pandoc |
| 32 | <https://pandoc.org>`__ - for example, to convert a ``.html`` file to ``.rst``, |
| 33 | you can run ``pandoc file.html -o file.rst``. |
| 34 | |
| 35 | Creating Diagrams |
| 36 | ----------------- |
| 37 | |
| 38 | The blockdiag suite of tools can be used for inline diagramming in ``.rst`` |
| 39 | files: |
| 40 | |
| 41 | - Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html |
| 42 | - Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html |
| 43 | |
| 44 | Attributes that can be applied to nodes: |
| 45 | http://blockdiag.com/en/blockdiag/attributes/node.attributes.html |
| 46 | |
| 47 | Examples: |
| 48 | |
| 49 | - blockdiag: http://blockdiag.com/en/blockdiag/examples.html |
| 50 | - nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html |
| 51 | - rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html |