From fef79dc7b9162e03c8891645494c115b52d4d014 Mon Sep 17 00:00:00 2001 From: Henry Gessau Date: Mon, 3 Aug 2015 23:30:34 -0400 Subject: [PATCH] Consistent layout and headings for devref The lack of convention for heading levels among the independently written devref documents was starting to make the Table of Contents look rather messy when rendered in HTML. This patch does not cover the "Neutron Internals" section since its layout is reasonably OK for now. Change-Id: I827c105599f05773bda7e4fc0a941ce04ebd51fa --- TESTING.rst | 37 +++++++-- .../devref/client_command_extensions.rst | 28 ++++++- doc/source/devref/contribute.rst | 25 +++++- doc/source/devref/development.environment.rst | 10 +++ doc/source/devref/fullstack_testing.rst | 38 +++++++-- doc/source/devref/index.rst | 9 ++ doc/source/devref/neutron_api.rst | 23 +++++ doc/source/devref/sub_projects.rst | 83 ++++++++++++------- 8 files changed, 204 insertions(+), 49 deletions(-) diff --git a/TESTING.rst b/TESTING.rst index ca71c0f5762..c30d77ea861 100644 --- a/TESTING.rst +++ b/TESTING.rst @@ -1,5 +1,28 @@ +.. + 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.) + + Testing Neutron -============================================================= +=============== Overview -------- @@ -183,7 +206,7 @@ see this wiki page: .. _virtualenvs: https://pypi.python.org/pypi/virtualenv PEP8 and Unit Tests -=================== ++++++++++++++++++++ Running pep8 and unit tests is as easy as executing this in the root directory of the Neutron source code:: @@ -204,7 +227,7 @@ To run only the unit tests:: tox -e py27 Functional Tests -================ +++++++++++++++++ To run functional tests that do not require sudo privileges or specific-system dependencies:: @@ -231,7 +254,7 @@ not necessary to provide this option if devstack has already been used to deploy Neutron to the target host. Fullstack Tests -=============== ++++++++++++++++ To run all the full-stack tests, you may use: :: @@ -248,7 +271,7 @@ sub-folder in /tmp/fullstack-logs (for example, a test named so that will be a good place to look if your test is failing. API Tests -========= ++++++++++ To run the api tests, deploy tempest and neutron with devstack and then run the following command: :: @@ -264,7 +287,7 @@ TEMPEST_CONFIG_DIR before invoking tox: :: Running individual tests ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ For running individual test modules or cases, you just need to pass the dot-separated path to the module you want as an argument to it. @@ -341,7 +364,7 @@ with pdb:: $ OS_POST_MORTEM_DEBUGGER=pudb ./run_tests.sh -d [test module path] References -========== +~~~~~~~~~~ .. [#pudb] PUDB debugger: https://pypi.python.org/pypi/pudb diff --git a/doc/source/devref/client_command_extensions.rst b/doc/source/devref/client_command_extensions.rst index f2bb8d83027..da9467dec68 100644 --- a/doc/source/devref/client_command_extensions.rst +++ b/doc/source/devref/client_command_extensions.rst @@ -1,9 +1,31 @@ -================================= +.. + 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.) + + Client command extension support -================================= +================================ The client command extension adds support for extending the neutron client while considering ease of creation. The full document can be found in the python-neutronclient repository: -http://docs.openstack.org/developer/python-neutronclient/devref/client_command_extensions.html \ No newline at end of file +http://docs.openstack.org/developer/python-neutronclient/devref/client_command_extensions.html diff --git a/doc/source/devref/contribute.rst b/doc/source/devref/contribute.rst index bf4f6ba5d74..d83de01b03a 100644 --- a/doc/source/devref/contribute.rst +++ b/doc/source/devref/contribute.rst @@ -1,3 +1,26 @@ +.. + 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.) + + Contributing new extensions to Neutron ====================================== @@ -546,6 +569,6 @@ Other repo-split items Decomposition Phase II Progress Chart -===================================== +------------------------------------- TBD. diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst index 21b90b4ebf2..a1c19f57e7c 100644 --- a/doc/source/devref/development.environment.rst +++ b/doc/source/devref/development.environment.rst @@ -15,6 +15,16 @@ 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.) + + Setting Up a Development Environment ==================================== diff --git a/doc/source/devref/fullstack_testing.rst b/doc/source/devref/fullstack_testing.rst index bc4c332e99b..67a827ab535 100644 --- a/doc/source/devref/fullstack_testing.rst +++ b/doc/source/devref/fullstack_testing.rst @@ -1,9 +1,31 @@ -========================== -Neutron Full Stack Testing -========================== +.. + 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.) + + +Full Stack Testing +================== Why? -==== +---- The idea behind "fullstack" testing is to fill a gap between unit + functional tests and Tempest. Tempest tests are expensive to run, difficult to run in @@ -14,7 +36,7 @@ environment and provide a rapidly reproducible way to verify code as you're still writing it. How? -==== +---- Full stack tests set up their own Neutron processes (Server & agents). They assume a working Rabbit and MySQL server before the run starts. Instructions @@ -44,7 +66,7 @@ interconnected. .. image:: images/fullstack-multinode-simulation.png When? -===== +----- 1) You'd like to test the interaction between Neutron components (Server and agents) and have already tested each component in isolation via unit or @@ -59,7 +81,7 @@ When? agent during the test. Short Term Goals -================ +---------------- * Multinode & Stability: - Convert the L3 HA failover functional test to a full stack test @@ -76,7 +98,7 @@ add full stack tests when appropriate in the patches themselves and not after the fact as there will probably be something to copy/paste from. Long Term Goals -=============== +--------------- * Currently we configure the OVS agent with VLANs segmentation (Only because it's easier). This allows us to validate most functionality, but we might diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst index 7ed6143c62c..390023e3702 100644 --- a/doc/source/devref/index.rst +++ b/doc/source/devref/index.rst @@ -15,6 +15,15 @@ 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.) + + Developer Guide =============== diff --git a/doc/source/devref/neutron_api.rst b/doc/source/devref/neutron_api.rst index 46492f0fccb..40b5d8a91b8 100644 --- a/doc/source/devref/neutron_api.rst +++ b/doc/source/devref/neutron_api.rst @@ -1,3 +1,26 @@ +.. + 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.) + + Neutron public API ================== diff --git a/doc/source/devref/sub_projects.rst b/doc/source/devref/sub_projects.rst index 9d6bed140f5..4b2aa44147a 100644 --- a/doc/source/devref/sub_projects.rst +++ b/doc/source/devref/sub_projects.rst @@ -1,3 +1,26 @@ +.. + 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.) + + Official Sub-Projects ===================== @@ -62,7 +85,7 @@ The official source of all repositories that exist under the Neutron project is: http://governance.openstack.org/reference/projects/neutron.html Affiliated projects -=================== +~~~~~~~~~~~~~~~~~~~ This table shows the affiliated projects that integrate with Neutron, in one form or another. These projects typically leverage the pluggable @@ -131,7 +154,7 @@ repo but are summarized here to describe the functionality they provide. +-------------------------------+-----------------------+ Functionality legend --------------------- +++++++++++++++++++++ - l2: a Layer 2 service; - ml2: an ML2 mechanism driver; @@ -145,7 +168,7 @@ Functionality legend .. _networking-arista: Arista ------- +++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-arista * Launchpad: https://launchpad.net/networking-arista @@ -154,7 +177,7 @@ Arista .. _networking-bagpipe-l2: BaGPipe -------- ++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-bagpipe-l2 * Launchpad: https://launchpad.net/bagpipe-l2 @@ -163,14 +186,14 @@ BaGPipe .. _networking-bgpvpn: BGPVPN -------- +++++++ * Git: https://git.openstack.org/cgit/openstack/networking-bgpvpn .. _networking-bigswitch: Big Switch Networks -------------------- ++++++++++++++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-bigswitch * Pypi: https://pypi.python.org/pypi/bsnstacklib @@ -178,7 +201,7 @@ Big Switch Networks .. _networking-brocade: Brocade -------- ++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-brocade * Launchpad: https://launchpad.net/networking-brocade @@ -187,7 +210,7 @@ Brocade .. _networking-cisco: Cisco ------ ++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-cisco * Launchpad: https://launchpad.net/networking-cisco @@ -196,7 +219,7 @@ Cisco .. _dragonflow: DragonFlow ----------- +++++++++++ * Git: https://git.openstack.org/cgit/openstack/dragonflow * Launchpad: https://launchpad.net/dragonflow @@ -205,7 +228,7 @@ DragonFlow .. _networking-edge-vpn: Edge VPN --------- +++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-edge-vpn * Launchpad: https://launchpad.net/edge-vpn @@ -213,7 +236,7 @@ Edge VPN .. _networking-fujitsu: FUJITSU -------- ++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-fujitsu * Launchpad: https://launchpad.net/networking-fujitsu @@ -222,7 +245,7 @@ FUJITSU .. _networking-hyperv: Hyper-V -------- ++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-hyperv * Launchpad: https://launchpad.net/networking-hyperv @@ -231,7 +254,7 @@ Hyper-V .. _group-based-policy: Group Based Policy ------------------- +++++++++++++++++++ * Git: https://git.openstack.org/cgit/stackforge/group-based-policy * Launchpad: https://launchpad.net/group-based-policy @@ -240,7 +263,7 @@ Group Based Policy .. _networking-ibm: IBM SDNVE ---------- ++++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-ibm * Launchpad: https://launchpad.net/networking-ibm @@ -248,7 +271,7 @@ IBM SDNVE .. _networking-l2gw: L2 Gateway ----------- +++++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-l2gw * Launchpad: https://launchpad.net/networking-l2gw @@ -256,7 +279,7 @@ L2 Gateway .. _networking-midonet: MidoNet -------- ++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-midonet * Launchpad: https://launchpad.net/networking-midonet @@ -265,7 +288,7 @@ MidoNet .. _networking-mlnx: Mellanox --------- +++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-mlnx * Launchpad: https://launchpad.net/networking-mlnx @@ -273,7 +296,7 @@ Mellanox .. _networking-nec: NEC ---- ++++ * Git: https://git.openstack.org/cgit/stackforge/networking-nec * Launchpad: https://launchpad.net/networking-nec @@ -282,14 +305,14 @@ NEC .. _nuage-openstack-neutron: Nuage ------ ++++++ * Git: https://github.com/nuage-networks/nuage-openstack-neutron .. _networking-odl: OpenDayLight ------------- +++++++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-odl * Launchpad: https://launchpad.net/networking-odl @@ -297,7 +320,7 @@ OpenDayLight .. _networking-ofagent: OpenFlow Agent (ofagent) ------------------------- +++++++++++++++++++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-ofagent * Launchpad: https://launchpad.net/networking-ofagent @@ -306,7 +329,7 @@ OpenFlow Agent (ofagent) .. _networking-ovn: Open Virtual Network --------------------- +++++++++++++++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-ovn * Launchpad: https://launchpad.net/networking-ovn @@ -315,7 +338,7 @@ Open Virtual Network .. _networking-ovs-dpdk: Open DPDK ---------- ++++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-ovs-dpdk * Launchpad: https://launchpad.net/networking-ovs-dpdk @@ -323,7 +346,7 @@ Open DPDK .. _networking-plumgrid: PLUMgrid --------- +++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-plumgrid * Launchpad: https://launchpad.net/networking-plumgrid @@ -332,7 +355,7 @@ PLUMgrid .. _neutron-powervm: PowerVM -------- ++++++++ * Git: https://git.openstack.org/cgit/stackforge/neutron-powervm * Launchpad: https://launchpad.net/neutron-powervm @@ -341,7 +364,7 @@ PowerVM .. _networking-portforwarding: PortForwarding --------------- +++++++++++++++ * Git: https://git.openstack.org/cgit/stackforge/networking-portforwarding * Launchpad: https://launchpad.net/networking-portforwarding @@ -349,14 +372,14 @@ PortForwarding .. _networking-sfc: SFC ---- ++++ * Git: https://git.openstack.org/cgit/openstack/networking-sfc .. _networking-vsphere: vSphere -------- ++++++++ * Git: https://git.openstack.org/cgit/openstack/networking-vsphere * Launchpad: https://launchpad.net/networking-vsphere @@ -364,7 +387,7 @@ vSphere .. _vmware-nsx: VMware NSX ----------- +++++++++++ * Git: https://git.openstack.org/cgit/openstack/vmware-nsx * Launchpad: https://launchpad.net/vmware-nsx @@ -373,7 +396,7 @@ VMware NSX .. _octavia: Octavia -------- ++++++++ * Git: https://git.openstack.org/cgit/openstack/octavia * Launchpad: https://launchpad.net/octavia