From 8cbc51cda465d7b0f1d860cce174aa3ed5340f2b Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Sun, 18 Jun 2017 03:23:46 +0900 Subject: [PATCH] move existing content into the new standard structure This patch rearranges and reformats existing content. Change-Id: Ibcad865d2ae45696628f77b5bd5f0e6b1f6842cf --- doc/source/cli/index.rst | 45 +++++++++++++++ doc/source/{usage/cli.rst => cli/neutron.rst} | 4 +- .../{usage => cli}/osc/v2/firewall-group.rst | 0 .../{usage => cli}/osc/v2/firewall-policy.rst | 0 .../{usage => cli}/osc/v2/firewall-rule.rst | 0 .../{usage => cli}/osc/v2/network-trunk.rst | 0 .../osc/v2/networking-bgpvpn.rst | 0 .../osc_plugins.rst} | 0 .../cli_option_guideline.rst | 0 .../client_command_extensions.rst | 0 doc/source/contributor/index.rst | 43 ++++++++++++++ .../transition_to_osc.rst | 0 doc/source/index.rst | 57 +++++++++++-------- .../library.rst => reference/index.rst} | 0 14 files changed, 122 insertions(+), 27 deletions(-) create mode 100644 doc/source/cli/index.rst rename doc/source/{usage/cli.rst => cli/neutron.rst} (99%) rename doc/source/{usage => cli}/osc/v2/firewall-group.rst (100%) rename doc/source/{usage => cli}/osc/v2/firewall-policy.rst (100%) rename doc/source/{usage => cli}/osc/v2/firewall-rule.rst (100%) rename doc/source/{usage => cli}/osc/v2/network-trunk.rst (100%) rename doc/source/{usage => cli}/osc/v2/networking-bgpvpn.rst (100%) rename doc/source/{usage/osc_cli_plugins.rst => cli/osc_plugins.rst} (100%) rename doc/source/{devref => contributor}/cli_option_guideline.rst (100%) rename doc/source/{devref => contributor}/client_command_extensions.rst (100%) create mode 100644 doc/source/contributor/index.rst rename doc/source/{devref => contributor}/transition_to_osc.rst (100%) rename doc/source/{usage/library.rst => reference/index.rst} (100%) 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 ` and +`OpenStack Client (OSC) `__. +OpenStack Client provides the basic network commands and +python-neutronclient provides :doc:`extensions ` (aka OSC plugins) +for advanced networking services. + +.. toctree:: + :maxdepth: 2 + + neutron CLI + Network extensions to OpenStack Client diff --git a/doc/source/usage/cli.rst b/doc/source/cli/neutron.rst similarity index 99% rename from doc/source/usage/cli.rst rename to 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 similarity index 100% rename from doc/source/usage/osc/v2/firewall-group.rst rename to 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 similarity index 100% rename from doc/source/usage/osc/v2/firewall-policy.rst rename to 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 similarity index 100% rename from doc/source/usage/osc/v2/firewall-rule.rst rename to 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 similarity index 100% rename from doc/source/usage/osc/v2/network-trunk.rst rename to 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 similarity index 100% rename from doc/source/usage/osc/v2/networking-bgpvpn.rst rename to 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 similarity index 100% rename from doc/source/usage/osc_cli_plugins.rst rename to doc/source/cli/osc_plugins.rst diff --git a/doc/source/devref/cli_option_guideline.rst b/doc/source/contributor/cli_option_guideline.rst similarity index 100% rename from doc/source/devref/cli_option_guideline.rst rename to 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 similarity index 100% rename from doc/source/devref/client_command_extensions.rst rename to 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 similarity index 100% rename from doc/source/devref/transition_to_osc.rst rename to 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 -` (the neutronclient module), and a :doc:`command-line script -` (installed as **neutron**). Each implements the entire OpenStack -Networking API. +This is a client for OpenStack Networking API. It provides +:doc:`Python API bindings ` (the neutronclient module) and +:doc:`command-line interface (CLI) `. -Using neutronclient -------------------- +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 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 `, 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 ------- diff --git a/doc/source/usage/library.rst b/doc/source/reference/index.rst similarity index 100% rename from doc/source/usage/library.rst rename to doc/source/reference/index.rst