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

3 files changed, 51 insertions, 21 deletions

diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
index c6efb1f..8ba5923 100644
--- a/doc/source/cli/index.rst
+++ b/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
-`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.
+`OpenStackClient (OSC)
+<https://docs.openstack.org/developer/python-openstackclient/>`__
+and :doc:`neutron CLI <neutron>` (deprecated).
+
+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>
-   Network extensions to OpenStack Client <osc_plugins>
+   neutron CLI guide <neutron>
diff --git a/doc/source/cli/neutron.rst b/doc/source/cli/neutron.rst
index 23ceadd..bc104ce 100644
--- a/doc/source/cli/neutron.rst
+++ b/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
 -----------
 
diff --git a/doc/source/cli/osc_plugins.rst b/doc/source/cli/osc_plugins.rst
index 343c3a9..0cd7e26 100644
--- a/doc/source/cli/osc_plugins.rst
+++ b/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
-can be referenced by doing ``openstack help network``.
+The following list covers the extended commands for advanced 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: