blob: cc797574c5655d68aa13837ff3c4c157e46f93db [file] [log] [blame]
Zack Williams071eda22019-05-15 18:19:51 -07001Documentation Guide
2===================
3
4Building the Docs
5------------------
6
7The documentation build process is stored in the Makefile. Building docs
8requires Python to be installed, and most steps will create a virtualenv
9(``doc_venv``) which install the documentation generation toolset.
10
11Run ``make html`` to generate html documentation in ``_build/html``.
12
13Run ``make reload`` to get a live reload in your browser (refreshes on document
14save).
15
16To check the formatting of documentation, run ``make lint``. This will be done
17in Jenkins to validate the documentation, so please do this before you create a
18patchset.
19
Zack Williamsc6460c22019-12-18 14:54:43 -070020To check spelling, run ``make spelling``. If there are additional words that
21are correctly spelled but not in the dictionary (acronyms, trademarks, etc.)
22please add them to the ``dict.txt`` file.
23
Zack Williams071eda22019-05-15 18:19:51 -070024Writing Docs
25------------
26
27Docs written using sphinx: http://www.sphinx-doc.org
28
29Documentation is done in reStructuredText (``.rst``) or Markdown (``.md``),
30but only .rst files can use certain features like embedded diagrams.
31
32reStructuredText Primer:
33http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
34
Zack Williams88df4742019-12-20 08:24:47 -070035Creating new Versions of Docs
36-----------------------------
37
38To change the version shown on the built site, change the ``versions`` variable in ``conf.py``.
39
40There is a ``make versioned`` target which will build all versions published on
41the remote to ``_build``. Note that we're using a fork of the upstream version
Zack Williamse377eae2019-12-20 16:40:38 -070042of the ``sphinxcontrib-versioning`` module, as the original isn't actively
43maintained, and we needed it to be able to handle the symlink checkouts of
Zack Williams88df4742019-12-20 08:24:47 -070044other repos that are incorporated.
45
Zack Williams071eda22019-05-15 18:19:51 -070046Creating Diagrams
47-----------------
48
49Inline Graphviz is supported:
50https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
51
52The blockdiag suite of tools can be used for other specific graph types:
53
54- Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html
55- Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html
56
57Attributes that can be applied to nodes:
58http://blockdiag.com/en/blockdiag/attributes/node.attributes.html
59
60Examples:
61
62- blockdiag: http://blockdiag.com/en/blockdiag/examples.html
63- nwdiag: http://blockdiag.com/en/nwdiag/nwdiag-examples.html
64- rackdiag: http://blockdiag.com/en/nwdiag/rackdiag-examples.html