Zack Williams | 071eda2 | 2019-05-15 18:19:51 -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 written using sphinx: http://www.sphinx-doc.org |
| 24 | |
| 25 | Documentation is done in reStructuredText (``.rst``) or Markdown (``.md``), |
| 26 | but only .rst files can use certain features like embedded diagrams. |
| 27 | |
| 28 | reStructuredText Primer: |
| 29 | http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html |
| 30 | |
| 31 | Creating Diagrams |
| 32 | ----------------- |
| 33 | |
| 34 | Inline Graphviz is supported: |
| 35 | https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html |
| 36 | |
| 37 | The blockdiag suite of tools can be used for other specific graph types: |
| 38 | |
| 39 | - Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html |
| 40 | - Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html |
| 41 | |
| 42 | Attributes that can be applied to nodes: |
| 43 | http://blockdiag.com/en/blockdiag/attributes/node.attributes.html |
| 44 | |
| 45 | Examples: |
| 46 | |
| 47 | - blockdiag: http://blockdiag.com/en/blockdiag/examples.html |
| 48 | - nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html |
| 49 | - rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html |