Initial Sphinx-based documentation templates and infra
Change-Id: I180ad109b8a885df6fd8911729289cee5c9bd99f
diff --git a/readme.rst b/readme.rst
new file mode 100644
index 0000000..6863626
--- /dev/null
+++ b/readme.rst
@@ -0,0 +1,51 @@
+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