From: Henry Gessau Date: Tue, 4 Aug 2015 03:30:34 +0000 (-0400) Subject: Consistent layout and headings for devref X-Git-Url: https://review.fuel-infra.org/gitweb?a=commitdiff_plain;h=fef79dc7b9162e03c8891645494c115b52d4d014;p=openstack-build%2Fneutron-build.git 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 --- diff --git a/TESTING.rst b/TESTING.rst index ca71c0f57..c30d77ea8 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 f2bb8d830..da9467dec 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 bf4f6ba5d..d83de01b0 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 21b90b4eb..a1c19f57e 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 bc4c332e9..67a827ab5 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 7ed6143c6..390023e37 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 46492f0fc..40b5d8a91 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 9d6bed140..4b2aa4414 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