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>

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:

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.
+

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
 

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

doc/source/quantumclient/client.py

@@ -0,0 +1,3 @@
+"""
+dummy module.
+"""

doc/source/quantumclient/common/exceptions.py

@@ -0,0 +1,7 @@
+"""
+dummy module.
+"""
+
+class QuantumClientException:
+    pass
+

doc/source/quantumclient/v2_0/client.py

@@ -0,0 +1,3 @@
+"""
+dummy module.
+"""

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

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

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:

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
+This module provides a basic set of REST API.
-#   - End-point port management
+
-#       - OpenFlow port number
+- Network registration
-#       - MAC address (for anti-spoofing)
+- End-point port management
-#
+    - OpenFlow port number
-# Used by OpenStack Ryu plug-in.
+    - MAC address (for anti-spoofing)
+
+Used by OpenStack Ryu plug-in.
+"""
 
 import json
 from webob import Response

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
+This module provides a set of REST API for switch configuration.
-#
+- Per-switch Key-Value store
-# Used by OpenStack Ryu agent.
+
+Used by OpenStack Ryu agent.
+"""
 
 import httplib
 import json

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
+This module provides a set of REST API dedicated to OpenStack Ryu plug-in.
-#   - Maintain interface association to a network
+
-#
+- Interface (uuid in ovsdb) registration
-# Used by OpenStack Ryu plug-in.
+- Maintain interface association to a network
+
+Used by OpenStack Ryu plug-in.
+"""
 
 import json
 from webob import Response

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
 

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
 

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
 

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

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

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

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

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

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

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
 

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__)

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

ryu/lib/ovs/__init__.py

@@ -0,0 +1,3 @@
+"""
+ovsdb interaction library.
+"""

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)

ryu/lib/xflow/__init__.py

@@ -0,0 +1,3 @@
+"""
+An implementation of sFlow and NetFlow.
+"""

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
 
 

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
 

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

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
 

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

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

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
 

ryu/topology/__init__.py

@@ -0,0 +1,3 @@
+"""
+Switch and link discovery module. Planned to replace ryu/controller/dpset.
+"""