openstack
/
neutron
Code Issues Proposed changes

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
This commit is contained in:
Henry Gessau 2015-08-03 23:30:34 -04:00
parent bbfd5cf486
commit fef79dc7b9
8 changed files with 204 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
TESTING.rst
View File

@ -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

28
doc/source/devref/client_command_extensions.rst
View File

@ -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
http://docs.openstack.org/developer/python-neutronclient/devref/client_command_extensions.html

25
doc/source/devref/contribute.rst
View File

@ -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.

10
doc/source/devref/development.environment.rst
View File

@ -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
====================================

38
doc/source/devref/fullstack_testing.rst
View File

@ -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

9
doc/source/devref/index.rst
View File

@ -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
===============

23
doc/source/devref/neutron_api.rst
View File

@ -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
==================

83
doc/source/devref/sub_projects.rst
View File

@ -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