doc: Describe how docs.openvswitch.org works

Signed-off-by: Stephen Finucane <stephen@that.guru>
Signed-off-by: Russell Bryant <russell@ovn.org>

3 files changed, 85 insertions, 0 deletions

diff --git a/Documentation/internals/contributing/documentation-style.rst b/Documentation/internals/contributing/documentation-style.rst
index f9da44cda..9fe473ce8 100644
--- a/Documentation/internals/contributing/documentation-style.rst
+++ b/Documentation/internals/contributing/documentation-style.rst
@@ -32,6 +32,12 @@ Open vSwitch. Documentation includes any documents found in ``Documentation``
 along with any ``README``, ``MAINTAINERS``, or generally ``rst`` suffixed
 documents found in the project tree.
 
+.. note::
+
+   This guide only applies to documentation for Open vSwitch v2.7. or greater.
+   Previous versions of Open vSwitch used a combination of Markdown and raw
+   plain text, and guidelines for these are not detailed here.
+
 reStructuredText vs. Sphinx
 ---------------------------
 
diff --git a/Documentation/internals/documentation.rst b/Documentation/internals/documentation.rst
new file mode 100644
index 000000000..eed98b4ba
--- /dev/null
+++ b/Documentation/internals/documentation.rst
@@ -0,0 +1,78 @@
+..
+      Copyright (c) 2017 Stephen Finucane <stephen@that.guru>
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+======================================
+How Open vSwitch's Documentation Works
+======================================
+
+This document provides a brief overview on how the documentation build system
+within Open vSwitch works. This is intended to maximize the "bus factor" and
+share best practices with other projects.
+
+reStructuredText and Sphinx
+---------------------------
+
+Nearly all of Open vSwitch's documentation is written in `reStructuredText`__,
+with man pages being the sole exception. Of this documentation, most of it is
+fed into `Sphinx`__, which provides not only the ability to convert rST to a
+variety of other output formats but also allows for things like
+cross-referencing and indexing. for more information on the two, refer to the
+:doc:`contributing/documentation-style`.
+
+ovs-sphinx-theme
+----------------
+
+The documentation uses its own theme, `ovs-sphinx-theme`, which can be found on
+GitHub__ and is published on pypi__. This is packaged separately from Open
+vSwitch itself to ensure all documentation gets the latest version of the theme
+(assuming there are no major version bumps in that package). If building
+locally and the package is installed, it will be used. If the package is not
+installed, Sphinx will fallback to the default theme.
+
+The package is currently maintained by Stephen Finucane and Russell Bryant.
+
+Read the Docs
+-------------
+
+The documentation is hosted on readthedocs.org and a CNAME redirect is in place
+to allow access from docs.openvswitch.org. *Read the Docs* provides a couple of
+nifty features for us, such as automatic building of docs whenever there are
+changes and versioning of documentation.
+
+The *Read the Docs* project is currently maintained by Stephen Finucane,
+Russell Bryant and Ben Pfaff.
+
+openvswitch.org
+---------------
+
+The sources for openvswitch.org are maintained separately from
+docs.openvswitch.org. For modifications to this site, refer to the `GitHub
+project`__.
+
+__ http://docutils.sourceforge.net/rst.html
+__ http://www.sphinx-doc.org/
+__ https://github.com/openvswitch/ovs-sphinx-theme
+__ https://pypi.python.org/pypi/ovs-sphinx-theme
+__ https://github.com/openvswitch/openvswitch.github.io
diff --git a/Documentation/internals/index.rst b/Documentation/internals/index.rst
index b0ae9b4e7..cf70f5566 100644
--- a/Documentation/internals/index.rst
+++ b/Documentation/internals/index.rst
@@ -43,3 +43,4 @@ itself and how they might involved.
    committer-grant-revocation
    authors
    maintainers
+   documentation