From c4ec6759b6aec38f1662ce0291ce87d9b5317c19 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Mon, 3 Jul 2017 17:11:57 +0900 Subject: [PATCH] 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 | 51 +++++++++++++++++++++----------- doc/source/cli/neutron.rst | 9 ++++++ doc/source/cli/osc_plugins.rst | 12 +++++--- doc/source/contributor/index.rst | 7 ----- doc/source/index.rst | 11 +++---- 5 files changed, 55 insertions(+), 35 deletions(-) diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst index c6efb1f4d..8ba5923b7 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 ` and -`OpenStack Client (OSC) `__. -OpenStack Client provides the basic network commands and -python-neutronclient provides :doc:`extensions ` (aka OSC plugins) -for advanced networking services. +`OpenStackClient (OSC) +`__ +and :doc:`neutron CLI ` (deprecated). + +OpenStackClient +--------------- + +OpenStackClient provides +`the basic network commands `__ +and python-neutronclient provides :doc:`extensions ` +(aka OSC plugins) for advanced networking services. + +.. toctree:: + :maxdepth: 1 + + Basic network commands + Network commands for advanced networking services + Mapping Guide from 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 + `__ + and :doc:`its extensions for advanced networking services `. + The command mapping from neutron CLI to openstack CLI is available + `here `__. .. toctree:: :maxdepth: 2 - neutron CLI - Network extensions to OpenStack Client + neutron CLI guide diff --git a/doc/source/cli/neutron.rst b/doc/source/cli/neutron.rst index 23ceadd23..bc104ce94 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 + `__ + and :doc:`its extensions for advanced networking services `. + The command mapping from neutron CLI to openstack CLI is available + `here `__. + Basic Usage ----------- diff --git a/doc/source/cli/osc_plugins.rst b/doc/source/cli/osc_plugins.rst index 343c3a9d3..0cd7e26ba 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 ``. .. toctree:: :glob: diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index ddbd7e8a4..f2150b0e0 100644 --- a/doc/source/contributor/index.rst +++ b/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 diff --git a/doc/source/index.rst b/doc/source/index.rst index bde3f3c43..9b7a0efc9 100644 --- a/doc/source/index.rst +++ b/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/cli_option_guideline - contributor/transition_to_osc + contributor/index .. note::