doc: Improve network CLI page

* Move OSC first as neutron CLI is deprecated
* Add more information on OSC usage (links to embeded command list
  and the mapping guide)
* Add deprecation notice for neutron CLI

This commit also makes toctree structure simpler
At now, we have two index page unlinked from the top page.
I thought it is good first, but it potentially makes things tricky.
Let's remove such tweaks for easy maintenance.

Change-Id: I7fd79f465fa6c04bf5b13f6578796d4c2d01edfd

doc/source/cli/index.rst

@@ -1,10 +1,3 @@
-: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
@@ -27,19 +20,43 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-=============
+=========
-CLI reference
+Using CLI
-=============
+=========
 
 There are two CLIs which support the Networking API:
-:doc:`neutron CLI <neutron>` and
+`OpenStackClient (OSC)
-`OpenStack Client (OSC) <https://docs.openstack.org/developer/python-openstackclient/>`__.
+<https://docs.openstack.org/developer/python-openstackclient/>`__
-OpenStack Client provides the basic network commands and
+and :doc:`neutron CLI <neutron>` (deprecated).
-python-neutronclient provides :doc:`extensions <osc_plugins>` (aka OSC plugins)
+
-for advanced networking services.
+OpenStackClient
+---------------
+
+OpenStackClient provides
+`the basic network commands <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__
+and python-neutronclient provides :doc:`extensions <osc_plugins>`
+(aka OSC plugins) for advanced networking services.
+
+.. toctree::
+   :maxdepth: 1
+
+   Basic network commands <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>
+   Network commands for advanced networking services <osc_plugins>
+   Mapping Guide from neutron CLI <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>
+
+neutron CLI
+-----------
+
+.. warning::
+
+   neutron CLI is now deprecated and will be removed in the future.
+   Use openstack CLI instead. See `openstack CLI command list
+   <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__
+   and :doc:`its extensions for advanced networking services <osc_plugins>`.
+   The command mapping from neutron CLI to openstack CLI is available
+   `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__.
 
 .. toctree::
    :maxdepth: 2
 
-   neutron CLI <neutron>
+   neutron CLI guide <neutron>
-   Network extensions to OpenStack Client <osc_plugins>

doc/source/cli/neutron.rst

@@ -26,6 +26,15 @@ 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.
 
+.. warning::
+
+   neutron CLI is now deprecated and will be removed in the future.
+   Use openstack CLI instead. See `openstack CLI command list
+   <https://docs.openstack.org/python-openstackclient/latest/cli/command-list.html>`__
+   and :doc:`its extensions for advanced networking services <osc_plugins>`.
+   The command mapping from neutron CLI to openstack CLI is available
+   `here <https://docs.openstack.org/python-openstackclient/latest/cli/decoder.html#neutron-cli>`__.
+
 Basic Usage
 -----------
 

doc/source/cli/osc_plugins.rst

@@ -20,11 +20,15 @@
       '''''''  Heading 4
       (Avoid deeper levels because they do not render well.)
 
-Using Network CLI extensions to OpenStack Client
+Advanced Network Commands in OpenStack Client
-================================================
+=============================================
 
-List of released CLI commands available in openstack client. These commands
+The following list covers the extended commands for advanced network
-can be referenced by doing ``openstack help network``.
+services available in ``openstack`` command.
+
+These commands can be referenced by doing ``openstack help`` and
+the detail of individual command can be referred by
+``openstack help <command-name>``.
 
 .. toctree::
    :glob:

doc/source/contributor/index.rst

@@ -1,10 +1,3 @@
-: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

doc/source/index.rst

@@ -38,11 +38,10 @@ User Documentation
 ------------------
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
+   cli/index
    reference/index
-   cli/neutron
-   cli/osc_plugins
 
 Contributor Guide
 -----------------
@@ -52,11 +51,9 @@ information on neutronclient's lower level programming details or APIs
 as well as the transition to OpenStack client.
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
-   contributor/client_command_extensions
+   contributor/index
-   contributor/cli_option_guideline
-   contributor/transition_to_osc
 
 .. note::