doc: add components page

port from wiki.

dummy quantumclient is necessary to import ryu.app.quantum_adapter by
sphinx.ext.autodoc.

Signed-off-by: Yoshihiro Kaneko <ykaneko0929@gmail.com>

39 files changed, 331 insertions, 18 deletions

diff --git a/doc/source/api_ref.rst b/doc/source/api_ref.rst
index cc0aad20..0f37f96e 100644
--- a/doc/source/api_ref.rst
+++ b/doc/source/api_ref.rst
@@ -11,5 +11,5 @@ Ryu API Reference
 .. autoclass:: ryu.base.app_manager.RyuApp
    :members: OFP_VERSIONS,_CONTEXTS,_EVENTS,close,context_iteritems,reply_to_request,send_event,send_event_to_observers,send_request,start
 
-.. automodule:: ryu.controller.dpset
+.. autoclass:: ryu.controller.dpset.DPSet
    :members:
diff --git a/doc/source/components.rst b/doc/source/components.rst
new file mode 100644
index 00000000..d7e53ecf
--- /dev/null
+++ b/doc/source/components.rst
@@ -0,0 +1,172 @@
+*****************
+Components of Ryu
+*****************
+
+Executables
+===========
+
+bin/ryu-manager
+---------------
+
+The main executable.
+
+
+Base components
+===============
+
+ryu.base.app_manager
+--------------------
+.. automodule:: ryu.base.app_manager
+
+
+OpenFlow controller
+===================
+
+ryu.controller.controller
+-------------------------
+.. automodule:: ryu.controller.controller
+
+ryu.controller.dpset
+--------------------
+.. automodule:: ryu.controller.dpset
+
+ryu.controller.ofp_event
+------------------------
+.. automodule:: ryu.controller.ofp_event
+
+ryu.controller.ofp_handler
+--------------------------
+.. automodule:: ryu.controller.ofp_handler
+
+
+OpenFlow wire protocol encoder and decoder
+==========================================
+
+ryu.ofproto.ofproto_v1_0
+------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_0
+
+ryu.ofproto.ofproto_v1_0_parser
+-------------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_0_parser
+
+ryu.ofproto.ofproto_v1_2
+------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_2
+
+ryu.ofproto.ofproto_v1_2_parser
+-------------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_2_parser
+
+ryu.ofproto.ofproto_v1_3
+------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_3
+
+ryu.ofproto.ofproto_v1_3_parser
+-------------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_3_parser
+
+ryu.ofproto.ofproto_v1_4
+------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_4
+
+ryu.ofproto.ofproto_v1_4_parser
+-------------------------------
+.. automodule:: ryu.ofproto.ofproto_v1_4_parser
+
+
+Ryu applications
+================
+
+ryu.app.cbench
+--------------
+.. automodule:: ryu.app.cbench
+
+ryu.app.simple_switch
+---------------------
+.. automodule:: ryu.app.simple_switch
+
+ryu.app.simple_isolation
+------------------------
+.. automodule:: ryu.app.simple_isolation
+
+ryu.app.simple_vlan
+-------------------
+.. automodule:: ryu.app.simple_vlan
+
+ryu.app.gre_tunnel
+------------------
+.. automodule:: ryu.app.gre_tunnel
+
+ryu.app.tunnel_port_updater
+---------------------------
+.. automodule:: ryu.app.tunnel_port_updater
+
+ryu.app.quantum_adapter
+-----------------------
+.. automodule:: ryu.app.quantum_adapter
+
+ryu.app.rest
+------------
+.. automodule:: ryu.app.rest
+
+ryu.app.rest_conf_switch
+------------------------
+.. automodule:: ryu.app.rest_conf_switch
+
+ryu.app.rest_quantum
+--------------------
+.. automodule:: ryu.app.rest_quantum
+
+ryu.app.rest_tunnel
+-------------------
+.. automodule:: ryu.app.rest_tunnel
+
+ryu.topology
+------------
+.. automodule:: ryu.topology
+
+
+Libraries
+=========
+
+ryu.lib.packet
+--------------
+.. automodule:: ryu.lib.packet
+
+ryu.lib.ovs
+-----------
+.. automodule:: ryu.lib.ovs
+
+ryu.lib.of_config
+-----------------
+.. automodule:: ryu.lib.of_config
+
+ryu.lib.netconf
+---------------
+.. automodule:: ryu.lib.netconf
+
+ryu.lib.xflow
+-------------
+.. automodule:: ryu.lib.xflow
+
+
+Third party libraries
+=====================
+
+ryu.contrib.ovs
+---------------
+
+Open vSwitch python binding. Used by ryu.lib.ovs.
+
+ryu.contrib.oslo.config
+-----------------------
+
+Oslo configuration library. Used for ryu-manager's command-line options
+and configuration files.
+
+ryu.contrib.ncclient
+--------------------
+
+Python library for NETCONF client. Used by ryu.lib.of_config.
+
diff --git a/doc/source/conf.py b/doc/source/conf.py
index a17bb223..4acad04d 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -17,6 +17,7 @@ import sys, os
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('../..'))
+sys.path.insert(0, os.path.abspath('.'))
 
 from ryu import version as ryu_version
 
diff --git a/doc/source/developing.rst b/doc/source/developing.rst
index d62dacf9..2e416744 100644
--- a/doc/source/developing.rst
+++ b/doc/source/developing.rst
@@ -6,6 +6,7 @@ Writing Your Ryu Application
    :maxdepth: 2
 
    writing_ryu_app.rst
+   components.rst
    ryu_app_api.rst
    library.rst
    ofproto_ref.rst
diff --git a/doc/source/quantumclient/__init__.py b/doc/source/quantumclient/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/source/quantumclient/__init__.py
diff --git a/doc/source/quantumclient/client.py b/doc/source/quantumclient/client.py
new file mode 100644
index 00000000..fbe444d4
--- /dev/null
+++ b/doc/source/quantumclient/client.py
@@ -0,0 +1,3 @@
+"""
+dummy module.
+"""
diff --git a/doc/source/quantumclient/common/__init__.py b/doc/source/quantumclient/common/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/source/quantumclient/common/__init__.py
diff --git a/doc/source/quantumclient/common/exceptions.py b/doc/source/quantumclient/common/exceptions.py
new file mode 100644
index 00000000..acbc46cd
--- /dev/null
+++ b/doc/source/quantumclient/common/exceptions.py
@@ -0,0 +1,7 @@
+"""
+dummy module.
+"""
+
+class QuantumClientException:
+    pass
+
diff --git a/doc/source/quantumclient/v2_0/__init__.py b/doc/source/quantumclient/v2_0/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/doc/source/quantumclient/v2_0/__init__.py
diff --git a/doc/source/quantumclient/v2_0/client.py b/doc/source/quantumclient/v2_0/client.py
new file mode 100644
index 00000000..fbe444d4
--- /dev/null
+++ b/doc/source/quantumclient/v2_0/client.py
@@ -0,0 +1,3 @@
+"""
+dummy module.
+"""
diff --git a/ryu/app/cbench.py b/ryu/app/cbench.py
index c84c62e7..aed83ab4 100644
--- a/ryu/app/cbench.py
+++ b/ryu/app/cbench.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+A dumb OpenFlow 1.0 responder for benchmarking the controller framework.
+Intended to be used with oflops cbench.
+"""
 
 from ryu.base import app_manager
 from ryu.controller import ofp_event
diff --git a/ryu/app/gre_tunnel.py b/ryu/app/gre_tunnel.py
index 3e9fbe72..aae910ac 100644
--- a/ryu/app/gre_tunnel.py
+++ b/ryu/app/gre_tunnel.py
@@ -18,6 +18,11 @@
 # Despite of the name, this module isn't GRE specific and
 # should work for VXLAN etc as well.
 
+"""
+Flow table updater for OpenStack integration. Despite of the name, this
+isn't GRE specific.
+"""
+
 import collections
 
 from ryu import exception as ryu_exc
diff --git a/ryu/app/quantum_adapter.py b/ryu/app/quantum_adapter.py
index bd1914fc..67aa6522 100644
--- a/ryu/app/quantum_adapter.py
+++ b/ryu/app/quantum_adapter.py
@@ -14,6 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Listen OpenFlow port status change notifications from switches. Consult
+ovsdb to retrieve the corresponding port uuid. Notify relevant parties,
+including quantum (via Ryu plug-in) and Ryu applications. (via Ryu Events)
+"""
+
 import traceback
 
 try:
diff --git a/ryu/app/rest.py b/ryu/app/rest.py
index dd394945..fdd19cac 100644
--- a/ryu/app/rest.py
+++ b/ryu/app/rest.py
@@ -14,13 +14,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module provides a basic set of REST API.
-#   - Network registration
-#   - End-point port management
-#       - OpenFlow port number
-#       - MAC address (for anti-spoofing)
-#
-# Used by OpenStack Ryu plug-in.
+"""
+This module provides a basic set of REST API.
+
+- Network registration
+- End-point port management
+    - OpenFlow port number
+    - MAC address (for anti-spoofing)
+
+Used by OpenStack Ryu plug-in.
+"""
 
 import json
 from webob import Response
diff --git a/ryu/app/rest_conf_switch.py b/ryu/app/rest_conf_switch.py
index adc5aabc..62b791c6 100644
--- a/ryu/app/rest_conf_switch.py
+++ b/ryu/app/rest_conf_switch.py
@@ -14,10 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module provides a set of REST API for switch configuration.
-#   - Per-switch Key-Value store
-#
-# Used by OpenStack Ryu agent.
+"""
+This module provides a set of REST API for switch configuration.
+- Per-switch Key-Value store
+
+Used by OpenStack Ryu agent.
+"""
 
 import httplib
 import json
diff --git a/ryu/app/rest_quantum.py b/ryu/app/rest_quantum.py
index 1820d5b8..4aeec530 100644
--- a/ryu/app/rest_quantum.py
+++ b/ryu/app/rest_quantum.py
@@ -14,11 +14,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module provides a set of REST API dedicated to OpenStack Ryu plug-in.
-#   - Interface (uuid in ovsdb) registration
-#   - Maintain interface association to a network
-#
-# Used by OpenStack Ryu plug-in.
+"""
+This module provides a set of REST API dedicated to OpenStack Ryu plug-in.
+
+- Interface (uuid in ovsdb) registration
+- Maintain interface association to a network
+
+Used by OpenStack Ryu plug-in.
+"""
 
 import json
 from webob import Response
diff --git a/ryu/app/rest_tunnel.py b/ryu/app/rest_tunnel.py
index b2786e93..74f5e461 100644
--- a/ryu/app/rest_tunnel.py
+++ b/ryu/app/rest_tunnel.py
@@ -14,6 +14,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Provide a set of REST API for tunnel key management. Used by OpenStack
+Ryu plug-in.
+
+- Tunnel key registration for a network
+- Manage switches and their ports which are used to establish a tunnel
+"""
+
 import json
 from webob import Response
 
diff --git a/ryu/app/simple_isolation.py b/ryu/app/simple_isolation.py
index c38cd9f1..d308c4a9 100644
--- a/ryu/app/simple_isolation.py
+++ b/ryu/app/simple_isolation.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+MAC address based isolation logic.
+"""
+
 import logging
 import struct
 
diff --git a/ryu/app/simple_switch.py b/ryu/app/simple_switch.py
index 6667c080..ffa8009f 100644
--- a/ryu/app/simple_switch.py
+++ b/ryu/app/simple_switch.py
@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+An OpenFlow 1.0 L2 learning switch implementation.
+"""
+
 import logging
 import struct
 
diff --git a/ryu/app/simple_vlan.py b/ryu/app/simple_vlan.py
index f18151ac..ea0e76fe 100644
--- a/ryu/app/simple_vlan.py
+++ b/ryu/app/simple_vlan.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+VLAN based isolation logic.
+"""
+
 from ryu.app import (conf_switch_key,
                      rest_nw_id)
 from ryu.base import app_manager
diff --git a/ryu/app/tunnel_port_updater.py b/ryu/app/tunnel_port_updater.py
index 0e8da305..6e25c8f8 100644
--- a/ryu/app/tunnel_port_updater.py
+++ b/ryu/app/tunnel_port_updater.py
@@ -14,7 +14,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module updates OVS tunnel ports for OpenStack integration.
+"""
+This module updates OVS tunnel ports for OpenStack integration.
+"""
 
 import collections
 from ryu import cfg
diff --git a/ryu/base/app_manager.py b/ryu/base/app_manager.py
index 387d6ce3..25b043aa 100644
--- a/ryu/base/app_manager.py
+++ b/ryu/base/app_manager.py
@@ -14,6 +14,15 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+The central management of Ryu applications.
+
+- Load Ryu applications
+- Provide `contexts` to Ryu applications
+- Route messages among Ryu applications
+
+"""
+
 import inspect
 import itertools
 import logging
diff --git a/ryu/controller/controller.py b/ryu/controller/controller.py
index a18d6668..23418f5f 100644
--- a/ryu/controller/controller.py
+++ b/ryu/controller/controller.py
@@ -14,6 +14,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+The main component of OpenFlow controller.
+
+- Handle connections from switches
+- Generate and route events to appropriate entities like Ryu applications
+
+"""
+
 import contextlib
 from ryu import cfg
 import logging
diff --git a/ryu/controller/dpset.py b/ryu/controller/dpset.py
index 399bed93..0d54fab4 100644
--- a/ryu/controller/dpset.py
+++ b/ryu/controller/dpset.py
@@ -14,6 +14,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Manage switches.
+
+Planned to be replaced by ryu/topology.
+"""
+
 import logging
 
 from ryu.base import app_manager
diff --git a/ryu/controller/ofp_event.py b/ryu/controller/ofp_event.py
index 43e7113b..16eb493a 100644
--- a/ryu/controller/ofp_event.py
+++ b/ryu/controller/ofp_event.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OpenFlow event definitions.
+"""
+
 import inspect
 
 from ryu.controller import handler
diff --git a/ryu/controller/ofp_handler.py b/ryu/controller/ofp_handler.py
index b95ff0ce..95f9a12d 100644
--- a/ryu/controller/ofp_handler.py
+++ b/ryu/controller/ofp_handler.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Basic OpenFlow handling including negotiation.
+"""
+
 import itertools
 import logging
 
diff --git a/ryu/lib/netconf/__init__.py b/ryu/lib/netconf/__init__.py
index 4cad86b2..c21554ca 100644
--- a/ryu/lib/netconf/__init__.py
+++ b/ryu/lib/netconf/__init__.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+NETCONF definitions used by ryu/lib/of_config.
+"""
+
 import os.path
 
 SCHEMA_DIR = os.path.dirname(__file__)
diff --git a/ryu/lib/of_config/__init__.py b/ryu/lib/of_config/__init__.py
index fe24fb9b..b2dbd05a 100644
--- a/ryu/lib/of_config/__init__.py
+++ b/ryu/lib/of_config/__init__.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OF-Config implementation.
+"""
+
 import glob
 import os.path
 import sys
diff --git a/ryu/lib/ovs/__init__.py b/ryu/lib/ovs/__init__.py
index e69de29b..8367e41d 100644
--- a/ryu/lib/ovs/__init__.py
+++ b/ryu/lib/ovs/__init__.py
@@ -0,0 +1,3 @@
+"""
+ovsdb interaction library.
+"""
diff --git a/ryu/lib/packet/__init__.py b/ryu/lib/packet/__init__.py
index cfd0f3d8..656fab44 100644
--- a/ryu/lib/packet/__init__.py
+++ b/ryu/lib/packet/__init__.py
@@ -1,2 +1,7 @@
+"""
+Ryu packet library. Decoder/Encoder implementations of popular protocols
+like TCP/IP.
+"""
+
 from . import (ethernet, arp, icmp, icmpv6, ipv4, ipv6, lldp, mpls, packet,
                packet_base, packet_utils)
diff --git a/ryu/lib/xflow/__init__.py b/ryu/lib/xflow/__init__.py
index e69de29b..356a50ea 100644
--- a/ryu/lib/xflow/__init__.py
+++ b/ryu/lib/xflow/__init__.py
@@ -0,0 +1,3 @@
+"""
+An implementation of sFlow and NetFlow.
+"""
diff --git a/ryu/ofproto/ofproto_v1_0.py b/ryu/ofproto/ofproto_v1_0.py
index d3d9edf4..2001a73c 100644
--- a/ryu/ofproto/ofproto_v1_0.py
+++ b/ryu/ofproto/ofproto_v1_0.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OpenFlow 1.0 definitions.
+"""
+
 from struct import calcsize
 
 
diff --git a/ryu/ofproto/ofproto_v1_0_parser.py b/ryu/ofproto/ofproto_v1_0_parser.py
index f01c222e..d4883019 100644
--- a/ryu/ofproto/ofproto_v1_0_parser.py
+++ b/ryu/ofproto/ofproto_v1_0_parser.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Decoder/Encoder implementations of OpenFlow 1.0.
+"""
+
 import struct
 import binascii
 
diff --git a/ryu/ofproto/ofproto_v1_2.py b/ryu/ofproto/ofproto_v1_2.py
index 50ea5cc4..345d0885 100644
--- a/ryu/ofproto/ofproto_v1_2.py
+++ b/ryu/ofproto/ofproto_v1_2.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OpenFlow 1.2 definitions.
+"""
+
 from ryu.ofproto import oxm_fields
 
 from struct import calcsize
diff --git a/ryu/ofproto/ofproto_v1_2_parser.py b/ryu/ofproto/ofproto_v1_2_parser.py
index 45917359..fe96520d 100644
--- a/ryu/ofproto/ofproto_v1_2_parser.py
+++ b/ryu/ofproto/ofproto_v1_2_parser.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Decoder/Encoder implementations of OpenFlow 1.2.
+"""
+
 import struct
 import itertools
 
diff --git a/ryu/ofproto/ofproto_v1_3.py b/ryu/ofproto/ofproto_v1_3.py
index d8442e1b..418bab1b 100644
--- a/ryu/ofproto/ofproto_v1_3.py
+++ b/ryu/ofproto/ofproto_v1_3.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OpenFlow 1.3 definitions.
+"""
+
 from ryu.ofproto import oxm_fields
 
 from struct import calcsize
diff --git a/ryu/ofproto/ofproto_v1_4.py b/ryu/ofproto/ofproto_v1_4.py
index 56d6a119..610a34e3 100644
--- a/ryu/ofproto/ofproto_v1_4.py
+++ b/ryu/ofproto/ofproto_v1_4.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+OpenFlow 1.4 definitions.
+"""
+
 from ryu.ofproto import oxm_fields
 
 from struct import calcsize
diff --git a/ryu/ofproto/ofproto_v1_4_parser.py b/ryu/ofproto/ofproto_v1_4_parser.py
index 7fac9d4d..701e4c42 100644
--- a/ryu/ofproto/ofproto_v1_4_parser.py
+++ b/ryu/ofproto/ofproto_v1_4_parser.py
@@ -14,6 +14,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Decoder/Encoder implementations of OpenFlow 1.4.
+"""
+
 import struct
 import itertools
 
diff --git a/ryu/topology/__init__.py b/ryu/topology/__init__.py
index e69de29b..66323335 100644
--- a/ryu/topology/__init__.py
+++ b/ryu/topology/__init__.py
@@ -0,0 +1,3 @@
+"""
+Switch and link discovery module. Planned to replace ryu/controller/dpset.
+"""