Convert our documentation to Sphinx.

faucetsdn · Dec 2, 2017 · 82da3e6 · 82da3e6
1 parent 465b847
commit 82da3e6
Show file tree

Hide file tree

Showing 58 changed files with 1,018 additions and 757 deletions.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,15 +1,8 @@
-============
 Contributing
 ============
-There is no formal process for contributions. Feel free to submit an issue or a
-pull request if you so desire. These will be reviewed by Brad, Josh or Kit.
-We'll either accept, close or offer feedback (or some combination).
-
-Code should pass all tests.
 
-For more detail see README.developerguide.rst in the docs directory
+Please see the `developer guide <https://faucet.readthedocs.io/en/latest/developer_guide.html>`_.
 
-=========
 Licensing
 =========
 This got a bit messy, so in the interest of clarifying things and tidying this

diff --git a/README.rst b/README.rst
@@ -6,7 +6,6 @@
 .. meta::
    :keywords: OpenFlow, Ryu, Faucet, VLAN, SDN
 
-======
 Faucet
 ======
 
@@ -24,12 +23,10 @@ It supports:
 - Controller health and statistics via Prometheus
 - Unit and systems tests run under Travis based on mininet and OVS
 
-
-====================================
 Hardware and software switch support
-====================================
+------------------------------------
 
-Detailed guides for some switches are available in `docs/vendors <docs/vendors>`_.
+Detailed guides for some switches are available on `readthedocs <https://faucet.readthedocs.io/en/latest/vendors/index.html>`_.
 
 FAUCET has been tested against the following switches (see also SUPPORTED_HARDWARE in `faucet/valve.py <faucet/valve.py>`_):
 
@@ -45,52 +42,38 @@ Faucet's design principle is to be as hardware agnostic as possible and not requ
 
 If you are a hardware vendor wanting to support FAUCET, you need to support all the matches in `faucet/valve.py <faucet/valve.py>`_ valve_in_match() and pass all tests.
 
-
-============
 Installation
-============
+------------
 
-Please see `docs/README_install.rst <docs/README_install.rst>`_
+Please see the `installation guide <https://faucet.readthedocs.io/en/latest/installation.html>`_.
 
-
-=============
 Configuration
-=============
-
-Please see `docs/README_config.rst <docs/README_config.rst>`_
+-------------
 
+Please see the `configuration guide <https://faucet.readthedocs.io/en/latest/configuration.html>`_
+for documentation regarding the general configuration of faucet and the
+`recipe book <https://faucet.readthedocs.io/en/latest/recipe_book/index.html>`_
+for configuration snippets for common use cases.
 
-=======================
 Development and testing
-=======================
+-----------------------
 
-Please see `docs/README.developerguide.rst <docs/README.developerguide.rst>`_
+Please see the `developer guide <https://faucet.readthedocs.io/en/latest/developer_guide.html>`_.
 
-
-=======
 Support
-=======
+-------
 
 We run a number of mailing lists for communication between users and developers of Faucet, as well as a low traffic mailing list for announcements of new versions:
 
 - https://list.waikato.ac.nz/mailman/listinfo/faucet-announce
 - https://list.waikato.ac.nz/mailman/listinfo/faucet-dev
 - https://lists.geant.org/sympa/info/faucet-users
 
-Additional documentation is available under the `docs <docs>`_ directory.
-
 Faucet blog by Josh Bailey available at http://faucet-sdn.blogspot.co.nz.
 
 To create a issue, use `GitHub Issues <https://github.com/faucetsdn/faucet/issues>`_.
 
-
-==================================
 Faucet deployment around the world
-==================================
-   https://www.google.com/maps/d/u/0/viewer?mid=1MZ0M9ZtZOp2yHWS0S-BQH0d3e4s&hl=en
-
-.. raw:: html
+----------------------------------
 
-  <div class="figure">
-  <iframe src="https://www.google.com/maps/d/u/0/embed?mid=1MZ0M9ZtZOp2yHWS0S-BQH0d3e4s" width="640" height="480"></iframe>
-  </div>
+`Faucet deployment map <https://www.google.com/maps/d/u/0/viewer?mid=1MZ0M9ZtZOp2yHWS0S-BQH0d3e4s&hl=en>`_
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build
diff --git a/docs/CouchDB_configuration.rst b/docs/CouchDB_configuration.rst
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,25 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+APIDOC        = sphinx-apidoc
+APIDOCOUTPUT  = source/apidoc
+APIDOCMODPATH = ../faucet
+APIDOCEXCLUDE =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = faucet
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(APIDOC) -o $(APIDOCOUTPUT) $(APIDOCMODPATH) $(APIDOCEXCLUDE)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/README.rst b/docs/README.rst
@@ -0,0 +1,16 @@
+Faucet Documentation
+====================
+
+
+Viewing documentation
+---------------------
+
+Docs are viewable on `readthedocs <https://faucet.readthedocs.io>`_.
+
+Building documentation
+----------------------
+
+.. code:: bash
+
+  sudo pip3 install -r requirements.txt
+  make html
diff --git a/docs/README_config.rst b/docs/README_config.rst
diff --git a/docs/deployments/ONF_Faucet_deploy1.png → ...static/deployments/ONF_Faucet_deploy1.png b/docs/deployments/ONF_Faucet_deploy1.png → ...static/deployments/ONF_Faucet_deploy1.png
diff --git a/.../deployments/nznog17-physical-network.jpg → .../deployments/nznog17-physical-network.jpg b/.../deployments/nznog17-physical-network.jpg → .../deployments/nznog17-physical-network.jpg
diff --git a/docs/deployments/nznog17-virtual-network.jpg → ...c/deployments/nznog17-virtual-network.jpg b/docs/deployments/nznog17-virtual-network.jpg → ...c/deployments/nznog17-virtual-network.jpg
diff --git a/docs/images/faucet-architecture.html → docs/_static/images/faucet-architecture.html b/docs/images/faucet-architecture.html → docs/_static/images/faucet-architecture.html
diff --git a/docs/images/faucet-architecture.png → docs/_static/images/faucet-architecture.png b/docs/images/faucet-architecture.png → docs/_static/images/faucet-architecture.png
diff --git a/docs/images/faucet-yaml.dot → docs/_static/images/faucet-yaml.dot b/docs/images/faucet-yaml.dot → docs/_static/images/faucet-yaml.dot
diff --git a/docs/images/faucet-yaml.png → docs/_static/images/faucet-yaml.png b/docs/images/faucet-yaml.png → docs/_static/images/faucet-yaml.png
diff --git a/docs/images/gauge-nznog17.png → docs/_static/images/gauge-nznog17.png b/docs/images/gauge-nznog17.png → docs/_static/images/gauge-nznog17.png
diff --git a/docs/images/gauge-snapshot1.png → docs/_static/images/gauge-snapshot1.png b/docs/images/gauge-snapshot1.png → docs/_static/images/gauge-snapshot1.png
diff --git a/docs/images/gauge-snapshot2.png → docs/_static/images/gauge-snapshot2.png b/docs/images/gauge-snapshot2.png → docs/_static/images/gauge-snapshot2.png
diff --git a/docs/images/gauge-snapshot3.png → docs/_static/images/gauge-snapshot3.png b/docs/images/gauge-snapshot3.png → docs/_static/images/gauge-snapshot3.png