Merge "move existing content into the new standard structure"

14 files changed, 122 insertions, 27 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..c6efb1f
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,45 @@
+:orphan:
+
+.. This page is to provide the top page for the CLI reference.
+   On the other hand, it looks better that the top level document has
+   direct links to individual pages for better navigation.
+   From that reason, :orphan: is needed to silence sphinx warning.
+
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+=============
+CLI reference
+=============
+
+There are two CLIs which support the Networking API:
+:doc:`neutron CLI <neutron>` and
+`OpenStack Client (OSC) <https://docs.openstack.org/developer/python-openstackclient/>`__.
+OpenStack Client provides the basic network commands and
+python-neutronclient provides :doc:`extensions <osc_plugins>` (aka OSC plugins)
+for advanced networking services.
+
+.. toctree::
+   :maxdepth: 2
+
+   neutron CLI <neutron>
+   Network extensions to OpenStack Client <osc_plugins>
diff --git a/doc/source/usage/cli.rst b/doc/source/cli/neutron.rst
index 4471ac3..23ceadd 100644
--- a/doc/source/usage/cli.rst
+++ b/doc/source/cli/neutron.rst
@@ -20,8 +20,8 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-Command-line Interface
-======================
+Using neutron CLI
+=================
 
 The **neutron** shell utility interacts with OpenStack Networking API from the
 command-line. It supports the entire features of OpenStack Networking API.
diff --git a/doc/source/usage/osc/v2/firewall-group.rst b/doc/source/cli/osc/v2/firewall-group.rst
index b0c24a8..b0c24a8 100644
--- a/doc/source/usage/osc/v2/firewall-group.rst
+++ b/doc/source/cli/osc/v2/firewall-group.rst
diff --git a/doc/source/usage/osc/v2/firewall-policy.rst b/doc/source/cli/osc/v2/firewall-policy.rst
index c4a78dd..c4a78dd 100644
--- a/doc/source/usage/osc/v2/firewall-policy.rst
+++ b/doc/source/cli/osc/v2/firewall-policy.rst
diff --git a/doc/source/usage/osc/v2/firewall-rule.rst b/doc/source/cli/osc/v2/firewall-rule.rst
index fdb5206..fdb5206 100644
--- a/doc/source/usage/osc/v2/firewall-rule.rst
+++ b/doc/source/cli/osc/v2/firewall-rule.rst
diff --git a/doc/source/usage/osc/v2/network-trunk.rst b/doc/source/cli/osc/v2/network-trunk.rst
index 06a63d2..06a63d2 100644
--- a/doc/source/usage/osc/v2/network-trunk.rst
+++ b/doc/source/cli/osc/v2/network-trunk.rst
diff --git a/doc/source/usage/osc/v2/networking-bgpvpn.rst b/doc/source/cli/osc/v2/networking-bgpvpn.rst
index 69b3150..69b3150 100644
--- a/doc/source/usage/osc/v2/networking-bgpvpn.rst
+++ b/doc/source/cli/osc/v2/networking-bgpvpn.rst
diff --git a/doc/source/usage/osc_cli_plugins.rst b/doc/source/cli/osc_plugins.rst
index 343c3a9..343c3a9 100644
--- a/doc/source/usage/osc_cli_plugins.rst
+++ b/doc/source/cli/osc_plugins.rst
diff --git a/doc/source/devref/cli_option_guideline.rst b/doc/source/contributor/cli_option_guideline.rst
index 49a8405..49a8405 100644
--- a/doc/source/devref/cli_option_guideline.rst
+++ b/doc/source/contributor/cli_option_guideline.rst
diff --git a/doc/source/devref/client_command_extensions.rst b/doc/source/contributor/client_command_extensions.rst
index 4b74cdf..4b74cdf 100644
--- a/doc/source/devref/client_command_extensions.rst
+++ b/doc/source/contributor/client_command_extensions.rst
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
new file mode 100644
index 0000000..ddbd7e8
--- /dev/null
+++ b/doc/source/contributor/index.rst
@@ -0,0 +1,43 @@
+:orphan:
+
+.. This page is to provide the top page for the contributor guide.
+   On the other hand, it looks better that the top level document has
+   direct links to individual pages for better navigation.
+   From that reason, :orphan: is needed to silence sphinx warning.
+
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+      Convention for heading levels in Neutron devref:
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+      (Avoid deeper levels because they do not render well.)
+
+=================
+Contributor Guide
+=================
+
+In the Contributor Guide, you will find information on neutronclient's
+lower level programming details or APIs as well as the transition to
+OpenStack client.
+
+.. toctree::
+   :maxdepth: 2
+
+   client_command_extensions
+   cli_option_guideline
+   transition_to_osc
diff --git a/doc/source/devref/transition_to_osc.rst b/doc/source/contributor/transition_to_osc.rst
index 2f0e524..2f0e524 100644
--- a/doc/source/devref/transition_to_osc.rst
+++ b/doc/source/contributor/transition_to_osc.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 8da1b76..bde3f3c 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -19,45 +19,52 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-Python bindings to the OpenStack Networking API
-===============================================
+==================================
+python-neutronclient documentation
+==================================
 
-This is a client for OpenStack Networking API. There is a :doc:`Python API
-<usage/library>` (the neutronclient module), and a :doc:`command-line script
-<usage/cli>` (installed as **neutron**). Each implements the entire OpenStack
-Networking API.
+This is a client for OpenStack Networking API. It provides
+:doc:`Python API bindings <reference/index>` (the neutronclient module) and
+:doc:`command-line interface (CLI) <cli/index>`.
 
-Using neutronclient
--------------------
+There are two CLIs which support the Networking API:
+:doc:`neutron CLI <cli/neutron>` and
+`OpenStack Client (OSC) <https://docs.openstack.org/developer/python-openstackclient/>`__.
+OpenStack Client provides the basic network commands and
+python-neutronclient provides extensions (aka OSC plugins)
+for advanced networking services.
+
+User Documentation
+------------------
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
+
+   reference/index
+   cli/neutron
+   cli/osc_plugins
 
-   usage/cli
-   usage/library
-   usage/osc_cli_plugins
+Contributor Guide
+-----------------
 
-Developer Guide
----------------
+In the :doc:`Contributor Guide <contributor/index>`, you will find
+information on neutronclient's lower level programming details or APIs
+as well as the transition to OpenStack client.
+
+.. toctree::
+   :maxdepth: 1
 
-In the Developer Guide, you will find information on Neutron’s client
-lower level programming details or APIs as well as the transition to
-OpenStack client.
+   contributor/client_command_extensions
+   contributor/cli_option_guideline
+   contributor/transition_to_osc
 
-.. note:
+.. note::
 
    neutron CLI has been deprecated from Ocata release.
    We do not add, change and drop any existing commands any more.
    We only accept changes on OSC plugin, neutronclient python bindings
    and bug fixes on the deprecated CLI (``neutron`` command).
 
-.. toctree::
-   :maxdepth: 2
-
-   devref/client_command_extensions
-   devref/cli_option_guideline
-   devref/transition_to_osc
-
 History
 -------
 
diff --git a/doc/source/usage/library.rst b/doc/source/reference/index.rst
index 8ab601c..8ab601c 100644
--- a/doc/source/usage/library.rst
+++ b/doc/source/reference/index.rst