[VOL-2875] Documentation update
- Updated the main landing page and overview documentation
- Added the lab setup (copied from CORD docs)
- Use forked sphinx-multiversion to publish docs, which allows versions
to be listed at bottom of sidebar
- Updated logo and favicon, fixed CSS to make logo legible
- Use VERSION file to set the version in the sidebar
- Add more words to dictionary
- removed reload functionality that is nonworking in Sphinx 2.x
- Fixed lint/linkcheck issues
Change-Id: I032e67d76393778fc697944a6d5df9c8cdacbbc4
diff --git a/readme.rst b/readme.rst
index cc79757..6beac1d 100644
--- a/readme.rst
+++ b/readme.rst
@@ -1,18 +1,32 @@
Documentation Guide
===================
+Writing Documentation
+---------------------
+
+Docs are generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+Documentation can be written in `reStructuredText
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/>`_ (``.rst``) or
+`Markdown <https://daringfireball.net/projects/markdown/>`_ (``.md``), but
+reStructuredText is preferred as that filetype supports features like embedded
+diagrams and tables.
+
+In reStructuredText documents, to create the section hierarchy (mapped in HTML
+to ``<h1>`` through ``<h5>``) use these characters to underline headings in the
+order given: ``=``, ``-`` ``"``, ``'``, ``^``.
+
Building the Docs
------------------
-The documentation build process is stored in the Makefile. Building 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.
+(``venv_docs``) which contains the required tools. You may also need to
+install the ``enchant`` C library using your system's package manager for the
+spelling checker to function properly.
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.
@@ -21,44 +35,38 @@
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: http://www.sphinx-doc.org
-
-Documentation is done in reStructuredText (``.rst``) or Markdown (``.md``),
-but only .rst files can use certain features like embedded diagrams.
-
-reStructuredText Primer:
-http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
-
Creating new Versions of Docs
-----------------------------
-To change the version shown on the built site, change the ``versions`` variable in ``conf.py``.
+To change the version shown on the built site, change the contents of the
+``VERSION`` file.
-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.
+There is a ``make multiversion`` target which will build all versions published
+on the remote to ``_build``. This will use a fork of `sphinx-multiversion
+<https://github.com/Holzhaus/sphinx-multiversion>`_ to build multiple versions
+for the site.
-Creating Diagrams
------------------
+Creating Graphs and Diagrams
+----------------------------
-Inline Graphviz is supported:
-https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html
+Multiple tools are available to render inline text-based graphs definitions and
+diagrams within the documentation. This is preferred over images as it's easier
+to change and see changes over time as a diff.
-The blockdiag suite of tools can be used for other specific graph types:
+`Graphviz
+<https://www.sphinx-doc.org/en/master/usage/extensions/graphviz.html>`_
+supports many standard graph types.
-- Block diagrams: http://blockdiag.com/en/blockdiag/sphinxcontrib.html
-- Network diagrams (& racks): http://blockdiag.com/en/nwdiag/sphinxcontrib.html
+The `blockdiag <http://blockdiag.com/en/blockdiag/sphinxcontrib.html>`_,
+`nwdiag, and rackdiag <http://blockdiag.com/en/nwdiag/sphinxcontrib.html>`_,
+and `seqdiag <http://blockdiag.com/en/seqdiag/sphinxcontrib.html>`_ suites of
+tools can be used to create specific types of diagrams:
-Attributes that can be applied to nodes:
-http://blockdiag.com/en/blockdiag/attributes/node.attributes.html
+- `blockdiag examples <http://blockdiag.com/en/blockdiag/examples.html>`_
+- `nwdiag examples <http://blockdiag.com/en/nwdiag/nwdiag-examples.html>`_
+- `rackdiag examples <http://blockdiag.com/en/nwdiag/rackdiag-examples.html>`_
+- `seqdiag examples <http://blockdiag.com/en/seqdiag/examples.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
+The styles applied to nodes and connections in these diagrams can be customized
+using `attributes
+<http://blockdiag.com/en/blockdiag/attributes/node.attributes.html>`_.