move existing content into the new standard structure

This patch rearranges and reformats existing content.

Change-Id: Ibcad865d2ae45696628f77b5bd5f0e6b1f6842cf

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>

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.

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

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
 
-   usage/cli
-   usage/library
-   usage/osc_cli_plugins
+   reference/index
+   cli/neutron
+   cli/osc_plugins
 
-Developer Guide
----------------
+Contributor Guide
+-----------------
 
-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.
+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.
 
-.. note:
+.. toctree::
+   :maxdepth: 1
+
+   contributor/client_command_extensions
+   contributor/cli_option_guideline
+   contributor/transition_to_osc
+
+.. 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
 -------