| Documentation Guide |
| =================== |
| |
| Building the 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 lint``. This will be done |
| in Jenkins to validate the documentation, so please do this before you create a |
| patchset. |
| |
| 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 |