blob: cc797574c5655d68aa13837ff3c4c157e46f93db [file] [log] [blame]
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
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
To check spelling, run ``make spelling``. If there are additional words that
are correctly spelled but not in the dictionary (acronyms, trademarks, etc.)
please add them to the ``dict.txt`` file.
Writing Docs
Docs written using sphinx:
Documentation is done in reStructuredText (``.rst``) or Markdown (``.md``),
but only .rst files can use certain features like embedded diagrams.
reStructuredText Primer:
Creating new Versions of Docs
To change the version shown on the built site, change the ``versions`` variable in ````.
There is a ``make versioned`` target which will build all versions published on
the remote to ``_build``. Note that we're using a fork of the upstream version
of the ``sphinxcontrib-versioning`` module, as the original isn't actively
maintained, and we needed it to be able to handle the symlink checkouts of
other repos that are incorporated.
Creating Diagrams
Inline Graphviz is supported:
The blockdiag suite of tools can be used for other specific graph types:
- Block diagrams:
- Network diagrams (& racks):
Attributes that can be applied to nodes:
- blockdiag:
- nwdiag:
- rackdiag: