Enhance the documentation structure

1. What is the problem

Currently all networking scenarios were put in one page
http://docs.openstack.org/developer/tricircle/networking-guide.html.
This is inconvinent for readers to navigate the content of different
scenarios.

At the same time, the configuration of service_plugins is missing
in local Neutron installation configuration items.

2. What is the solution to the problem
Add one more level, to make each networking scenario being rendered
in different page. This adjustment will also lead to the title level
adjustment of installation-manual.

Add the service_plugins configuration item in
installation_manual.rst.

3. What the features need to be implemented to the Tricircle
No new features

Change-Id: I84a95abfea6aa023c8958d520c4fce028bd10e17
Signed-off-by: joehuang <joehuang@huawei.com>

doc/source/configuration.rst

@@ -186,3 +186,40 @@ Neutron's neutron.conf
      - (String) Central Neutron server url, for example, http://$service_host:9696
    * - ``real_core_plugin`` = ``None``
      - (String) The core plugin the Tricircle local plugin will invoke, for example, neutron.plugins.ml2.plugin.Ml2Plugin
+
+
+**Tricircle Local Neutron L3 Plugin**
+
+In multiple OpenStack clouds, if the external network is located in the
+first OpenStack cloud, but the port which will be associated with one
+floating ip is located in the second OpenStack cloud, then the network for
+this port may not be able to be added to the router in the first OpenStack.
+In Tricircle, to address this scenario, a bridge network will be used
+to connect the routers in these two OpenStack clouds if the network is not
+a cross Neutron L2 network. To make it happen, the Tricircle Local Neutron L3
+Plugin or other L3 service plugin should be able to associate a floating ip to
+a port whose network is not directly attached to the router. TricircleL3Plugin
+is inherited from Neutron original L3RouterPlugin, and overrides the original
+"get_router_for_floatingip" implementation to allow associating a floating ip
+to a port whose network is not directly attached to the router. If you want
+to configure local Neutron to use original L3RouterPlugin, then you need to
+patch the function "get_router_for_floatingip" as what has been done in
+TricircleL3Plugin.
+
+If only cross Neutron L2 networking is needed in the deployment, it's not
+necessary to configure the service plugins.
+
+The following item should be configured in local Neutron's neutron.conf
+
+.. _Local Neutron:
+
+.. list-table:: Description of Local Neutron configuration options
+   :header-rows: 1
+   :class: config-ref-table
+
+   * - Configuration option = Default value
+     - Description and Example
+   * - **[DEFAULT]**
+     -
+   * - ``service_plugins`` = ``None``
+     - (String) service plugins local Neutron server uses, can be set to tricircle.network.local_l3_plugin.TricircleL3Plugin

doc/source/index.rst

@@ -11,7 +11,7 @@ Contents
 ========
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
 
    readme
    usage

doc/source/installation-manual.rst

@@ -17,7 +17,7 @@ the Tricircle administrator service needs to be registered in this region along
 with central Neutron service while other core services are not mandatory.
 
 Installation with Central Neutron Server
-========================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - 1 Install the Tricircle package::
 
@@ -183,7 +183,7 @@ Installation with Central Neutron Server
   - start central Neutron server
 
 Installation with Local Neutron Server
-======================================
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - 1 Install the Tricircle package::
 
@@ -202,12 +202,28 @@ Installation with Local Neutron Server
 
   - configure local Neutron server
 
-    edit neutron.conf
+    edit neutron.conf.
+
+    .. note::
+
+      Pay attention to the service_plugins configuration item, make sure
+      the plugin which is configured can support associating a floating ip to
+      a port whose network is not directly attached to the router.
+      TricircleL3Plugin is inherited from Neutron original L3RouterPlugin,
+      and overrides the original "get_router_for_floatingip" implementation
+      to allow associating a floating ip to a port whose network is not
+      directly attached to the router. If you want to configure local Neutron
+      to use original L3RouterPlugin, then you need to patch the function
+      "get_router_for_floatingip" as what has been done in TricircleL3Plugin.
+
+      If only cross Neutron L2 networking is needed in the deployment, it's
+      not necessary to configure the service plugins.
 
   .. csv-table::
      :header: "Option", "Description", "Example"
 
      [DEFAULT] core_plugin, "core plugin local Neutron server uses", tricircle.network.local_plugin.TricirclePlugin
+     [DEFAULT] service_plugins, "service plugins local Neutron server uses", tricircle.network.local_l3_plugin.TricircleL3Plugin
      [client] auth_url, "keystone authorization url", http://$keystone_service_host:5000/v3
      [client] identity_url, "keystone service url", http://$keystone_service_host:35357/v3
      [client] auto_refresh_endpoint, "if set to True, endpoint will be automatically refreshed if timeout accessing", True

doc/source/networking-guide.rst

@@ -1,12 +1,11 @@
 Networking Guide
-----------------
+================
+
 The Tricircle is to provide networking automation across Neutron
 servers in multi-region OpenStack clouds deployment, many cross Neutron
 networking mode are supported. In this guide, how to use CLI to setup
 typical networking mode will be described.
 
+
 .. include:: ./networking-prerequisites.rst
-.. include:: ./networking-guide-direct-provider-networks.rst
-.. include:: ./networking-guide-multiple-external-networks.rst
-.. include:: ./networking-guide-single-external-network.rst
-.. include:: ./networking-guide-local-networking.rst
+.. include:: ./networking-senarios.rst

doc/source/networking-senarios.rst

@@ -0,0 +1,11 @@
+===================
+Networking Scenario
+===================
+
+.. toctree::
+    :maxdepth: 3
+
+    networking-guide-direct-provider-networks.rst
+    networking-guide-multiple-external-networks.rst
+    networking-guide-single-external-network.rst
+    networking-guide-local-networking.rst