doc: Usage for ryu/services/protocols/bgp/application.py

Signed-off-by: IWASE Yusuke <iwase.yusuke0@gmail.com>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

3 files changed, 98 insertions, 29 deletions

diff --git a/doc/source/app.rst b/doc/source/app.rst
index 69376dba..eb8bbc20 100644
--- a/doc/source/app.rst
+++ b/doc/source/app.rst
@@ -12,3 +12,4 @@ Others provide some functionalities to other Ryu applications.
    app/ofctl.rst
    app/ofctl_rest.rst
    app/rest_vtep.rst
+   app/bgp_application.rst
diff --git a/doc/source/app/bgp_application.rst b/doc/source/app/bgp_application.rst
new file mode 100644
index 00000000..47e9fa89
--- /dev/null
+++ b/doc/source/app/bgp_application.rst
@@ -0,0 +1,6 @@
+**************************************
+ryu.services.protocols.bgp.application
+**************************************
+
+.. automodule:: ryu.services.protocols.bgp.application
+   :members:
diff --git a/ryu/services/protocols/bgp/application.py b/ryu/services/protocols/bgp/application.py
index ed5961b8..df3e9b95 100644
--- a/ryu/services/protocols/bgp/application.py
+++ b/ryu/services/protocols/bgp/application.py
@@ -14,7 +14,97 @@
 # limitations under the License.
 
 """
-  Defines bases classes to create a BGP application.
+This module provides a convenient application for using Ryu BGPSpeaker and for
+writing your BGP application.
+
+It reads a configuration file which includes settings for neighbors, routes
+and some others.
+Please refer to ``ryu/services/protocols/bgp/bgp_sample_conf.py`` for the
+sample configuration.
+
+Usage Example::
+
+    $ ryu-manager ryu/services/protocols/bgp/application.py \\
+        --bgp-app-config-file ryu/services/protocols/bgp/bgp_sample_conf.py
+
+SSH Console
+===========
+
+You can also use the SSH console and see the RIB and do some operations from
+this console.
+The SSH port and username/password can be configured by the configuration file.
+You can check the help by hitting '?' key in this interface.
+
+Example::
+
+    $ ssh localhost -p 4990
+
+    Hello, this is Ryu BGP speaker (version 4.19).
+
+    bgpd> # Hit '?' key
+     clear - allows to reset BGP connections
+     help - show this help
+     quit - exit this session
+     set - set runtime settings
+     show - shows runtime state information
+    bgpd>
+    bgpd> show rib all
+    Status codes: * valid, > best
+    Origin codes: i - IGP, e - EGP, ? - incomplete
+         Network        Labels   Next Hop   Reason      Metric LocPrf Path
+     *>  10.10.1.0/24   None     0.0.0.0    Only Path                 i
+    bgpd>
+
+Integration with Other Applications
+===================================
+
+``ryu.services.protocols.bgp.application.RyuBGPSpeaker`` will notifies the
+following events to other Ryu applications.
+
+    - ``EventBestPathChanged``
+    - ``EventPeerDown``
+    - ``EventPeerUp``
+
+To catch these events, specify ``@set_ev_cls()`` decorator to the event
+handlers in the Ryu applications.
+
+Example Application::
+
+    # my_bgp_app.py
+
+    from ryu.base import app_manager
+    from ryu.controller.handler import set_ev_cls
+    from ryu.services.protocols.bgp import application as bgp_application
+
+
+    class MyBGPApp(app_manager.RyuApp):
+        _CONTEXTS = {
+            'ryubgpspeaker': bgp_application.RyuBGPSpeaker,
+        }
+
+        def __init__(self, *args, **kwargs):
+            super(MyBGPApp, self).__init__(*args, **kwargs)
+
+            # Stores "ryu.services.protocols.bgp.application.RyuBGPSpeaker"
+            # instance in order to call the APIs of
+            # "ryu.services.protocols.bgp.bgpspeaker.BGPSpeaker" via
+            # "self.app.speaker".
+            # Please note at this time, "BGPSpeaker" is NOT instantiated yet.
+            self.app = kwargs['ryubgpspeaker']
+
+        @set_ev_cls(bgp_application.EventBestPathChanged)
+        def _best_patch_changed_handler(self, ev):
+            self.logger.info(
+                'Best path changed: is_withdraw=%s, path=%s',
+                ev.is_withdraw, ev.path)
+
+Usage Example::
+
+    $ ryu-manager my_bgp_app.py \\
+        --bgp-app-config-file ryu/services/protocols/bgp/bgp_sample_conf.py
+
+API Reference
+=============
 """
 
 import logging
@@ -140,34 +230,6 @@ class EventPeerUp(EventBase):
 class RyuBGPSpeaker(RyuApp):
     """
     Base application for implementing BGP applications.
-
-    This application will notifies
-     - ``EventBestPathChanged``
-     - ``EventPeerDown``
-     - ``EventPeerUp``
-    to other BGP applications.
-    To catch these events, specify ``@set_ev_cls()`` decorator to the event
-    handlers in the Ryu applications.
-
-    Example::
-
-        ...
-        from ryu.base import app_manager
-        from ryu.controller.handler import set_ev_cls
-        from ryu.services.protocols.bgp import application as bgp_application
-        ...
-
-        class MyBGPApp(app_manager.RyuApp):
-            _CONTEXTS = {
-                'ryubgpspeaker': bgp_application.RyuBGPSpeaker,
-            }
-
-            ...
-            @set_ev_cls(bgp_application.EventBestPathChanged)
-            def _best_patch_changed_handler(self, ev):
-                self.logger.info(
-                    'Best path changed: is_withdraw=%s, path=%s',
-                    ev.is_withdraw, ev.path)
     """
     _EVENTS = [
         EventBestPathChanged,