Convert our documentation to Sphinx.

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

Hide file tree

Showing 52 changed files with 842 additions and 581 deletions.
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.md b/docs/README.md
@@ -0,0 +1,8 @@
+## Viewing documentation
+
+Docs are viewable on (readthedocs)[https://faucet.readthedocs.io/]
+
+## Building documentation
+
+$ 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
diff --git a/docs/architecture.rst b/docs/architecture.rst
@@ -1,12 +1,8 @@
-:copyright: 2015--2017 The Contributors
-:Authors: - Shivaram Mysore
-
-.. meta::
-   :keywords: Openflow, Ryu, Faucet, VLAN, SDN
+Architecture
+============
 
-==============================
 Faucet Design and Architecture
-==============================
+------------------------------
 
 Faucet enables practical SDN for the masses (see http://queue.acm.org/detail.cfm?id=3015763).
 
@@ -21,10 +17,9 @@ Faucet enables practical SDN for the masses (see http://queue.acm.org/detail.cfm
 
 See unit and integration tests for working configuration examples.
 
-
-===============================
 Faucet Openflow Switch Pipeline
-===============================
+-------------------------------
+
 ::
 
     PACKETS IN                  +-------------------------+  +-------------------------------------+
@@ -49,14 +44,12 @@ Faucet Openflow Switch Pipeline
                                                                                          v
                                                                                     CONTROLLER
 
-------------
 Table 0: PORT_ACL
-------------
+~~~~~~~~~~~~~~~~~
 - Apply user supplied ACLs to a port and send to next table
 
--------------
 Table 1: VLAN
--------------
+~~~~~~~~~~~~~
 
 - Match fields: ``eth_dst, eth_type, in_port, vlan_vid``
 - Operations:
@@ -67,23 +60,20 @@ Table 1: VLAN
         - Push VLAN frame onto packet with VLAN_VID representing ports native VLAN and send to next table
     - Unknown traffic is dropped
 
-------------
 Table 2: VLAN_ACL
-------------
+~~~~~~~~~~~~~~~~~
 - Apply user supplied ACLs to a VLAN and send to next table
 
-----------------
 Table 3: ETH_SRC
-----------------
+~~~~~~~~~~~~~~~~
 - Match fields: ``eth_dst, eth_src, eth_type, in_port, vlan_vid``
 - Operations:
     - For IPv4/IPv6 traffic where Faucet is the next hop, send to IPV4_FIB or IPV6_FIB (route)
     - For known source MAC, send to ETH_DST (switch)
     - For unknown source MACs, copy header to controller via packet in (for learning) and send to FLOOD
 
------------------
 Table 4: IPV4_FIB
------------------
+~~~~~~~~~~~~~~~~~
 - Match fields: ``eth_type, ipv4_dst, vlan_vid``
 - Operations:
     - Route IPv4 traffic to a next-hop for each route we have learned
@@ -93,9 +83,8 @@ Table 4: IPV4_FIB
     - Send to ETH_DST table
     - Unknown traffic is dropped
 
------------------
 Table 5: IPV6_FIB
------------------
+~~~~~~~~~~~~~~~~~
 - Match fields: ``eth_type, ipv6_dst, vlan_vid``
 - Operations:
     - Route IPv4 traffic to a next-hop for each route we have learned
@@ -105,46 +94,30 @@ Table 5: IPV6_FIB
     - Send to ETH_DST table
     - Unknown traffic is dropped
 
-----------------
 Table 6: VIP
-----------------
+~~~~~~~~~~~~
 
 - Match fields: ``arp_tpa, eth_dst, eth_type, icmpv6_type, ip_proto``
 - Operations:
     - Send traffic destined for FAUCET VIPs including IPv4 ARP and IPv6 ND to the controller.
     - IPv6 ND traffic may be flooded also (sent to FLOOD)
 
-----------------
 Table 7: ETH_DST
-----------------
+~~~~~~~~~~~~~~~~
 - Match fields: ``eth_dst, in_port, vlan_vid``
 - Operations:
     - For destination MAC addresses we have learned output packet towards that host (popping VLAN frame if we are outputting on an untagged port)
     - Unknown traffic is sent to FLOOD table
 
---------------
 Table 8: FLOOD
---------------
+~~~~~~~~~~~~~~
 - Match fields: ``eth_dst, in_port, vlan_vid``
 - Operations:
     - Flood broadcast within VLAN
     - Flood multicast within VLAN
     - Unknown traffic is flooded within VLAN
 
-
-===================
 Faucet Architecture
-===================
-.. image:: /docs/images/faucet-architecture.png
-
-
-============
-UML Diagrams
-============
-.. image:: /docs/images/faucet-classes.png
-
+-------------------
 
-=======================
-Deployment Architecture
-=======================
-.. image:: /docs/deployments/simple.png
+.. image:: /_static/images/faucet-architecture.png