Start of new developer documentation

There is currently no useful developer-focused documentation in-tree
for Neutron. There are a smattering of useful documents on the
OpenStack wiki, however, there isn't a good organization to this
information, nor is there a condensed developer focus to a lot of it.
Some of the wiki pages are more proposals for features or bug fixes,
and there is a need for architecture, design, and code walk-through
documentation for Neutron to help with new (and existing) contribution.

This patch begins the process of adding developer documentation to Neutron.
It updates the main developer reference index.rst to pull in-line with what
Nova is doing, leaving some todo references for future patches. It also
adds a development.environment tutorial that is up-to-date with current
Neutron development, using tox/testr processes for running unit tests and
including a number of references to external wiki pages that have
instructions for using DevStack for OpenStack contribution/testing.

The next series of patches will add automodule documentation to the
developer reference for some of the major modules in Neutron.

Change-Id: I23aaa11d9a174f24242c49767b92540f5e25b48a
Addresses: blueprint quantum-developer-docs
This commit is contained in:
Jay Pipes 2013-12-26 16:04:19 -05:00
parent e3797e36a4
commit 3a9306054b
3 changed files with 149 additions and 11 deletions

View File

@ -0,0 +1,107 @@
..
Copyright 2010-2013 United States Government as represented by the
Administrator of the National Aeronautics and Space Administration.
All Rights Reserved.
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.
Setting Up a Development Environment
====================================
This page describes how to setup a working Python development
environment that can be used in developing Neutron on Ubuntu, Fedora or
Mac OS X. These instructions assume you're already familiar with
Git and Gerrit, which is a code repository mirror and code review toolset
, however if you aren't please see `this Git tutorial_` for an introduction
to using Git and `this wiki page_` for a tutorial on using Gerrit and Git for
code contribution to Openstack projects.
.. _this Git tutorial: http://git-scm.com/book/en/Getting-Started
.. _this wiki page: https://wiki.openstack.org/wiki/Gerrit_Workflow
Following these instructions will allow you to run the Neutron unit
tests. If you want to be able to run Neutron in a full OpenStack environment,
you can use the excellent `DevStack_` project to do so. There is a wiki page
that describes `setting up Neutron using DevStack_`.
.. _DevStack: https://github.com/openstack-dev/devstack
.. _setting up Neutron using Devstack: https://wiki.openstack.org/wiki/NeutronDevstack
Virtual environments
--------------------
Testing OpenStack projects, including Neutron, is made easier with `DevStack_`.
Create a machine (such as a VM or Vagrant box) running a distribution supported
by DevStack and install DevStack there. For example, there is a Vagrant script
for DevStack at https://github.com/jogo/DevstackUp.
.. note::
If you prefer not to use DevStack, you can still check out source code on your local
machine and develop from there.
Getting the code
----------------
Grab the code from GitHub::
git clone git://git.openstack.org/openstack/neutron.git
cd neutron
Running unit tests
------------------
With `run_tests.sh`
~~~~~~~~~~~~~~~~~~~
You can use the `run_tests.sh` script in the root source directory to execute
tests in a virtualenv:
./run_tests -V
With `tox`
~~~~~~~~~~
Neutron, like other OpenStack projects, uses `tox_` for managing the virtual
environments for running test cases. It uses `Testr_` for managing the running
of the test cases.
Tox handles the creation of a series of `virtualenvs_` that target specific
versions of Python (2.6, 2.7, 3.3, etc).
Testr handles the parallel execution of series of test cases as well as
the tracking of long-running tests and other things.
Running unit tests is as easy as executing this in the root directory of the
Neutron source code::
tox
For more information on the standard Tox-based test infrastructure used by
OpenStack and how to do some common test/debugging procedures with Testr,
see this wiki page:
https://wiki.openstack.org/wiki/Testr
.. _Testr: https://wiki.openstack.org/wiki/Testr
.. _tox: http://tox.readthedocs.org/en/latest/
.. _virtualenvs: https://pypi.python.org/pypi/virtualenv
Using a remote debugger
-----------------------
.. todo:: Beef up and add examples to content at
https://wiki.openstack.org/wiki/NeutronDevelopment#How_to_debug_Neutron_.28and_other_OpenStack_projects_probably_.29

View File

@ -18,6 +18,33 @@
Developer Guide
===============
The `Neutron Wiki`_ is a very good place to start.
In the Developer Guide, you will find information on Neutron's lower level
programming APIs. There are sections that cover the core pieces of Neutron,
including its database, message queue, and scheduler components. There are
also subsections that describe specific plugins inside Neutron.
.. _`Neutron wiki`: http://wiki.openstack.org/Neutron
Programming HowTos and Tutorials
--------------------------------
.. toctree::
:maxdepth: 3
development.environment
Module Reference
----------------
.. toctree::
:maxdepth: 3
.. todo::
Add in all the big modules as automodule indexes.
Indices and tables
------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

View File

@ -1,5 +1,5 @@
..
Copyright 2011 OpenStack Foundation
Copyright 2011-2013 OpenStack Foundation
All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License"); you may
@ -19,9 +19,9 @@ Welcome to Neutron's developer documentation!
Neutron is an OpenStack project to provide "network connectivity as a service"
between interface devices (e.g., vNICs) managed by other Openstack services
(e.g., nova). It implements the `Neutron API Guide`_.
(e.g., nova). It implements the `Neutron API`_.
.. _`Neutron API Guide`: http://docs.openstack.org/incubation/openstack-network/developer/quantum-api-1.0/content/
.. _`Neutron API`: http://docs.openstack.org/api/openstack-network/2.0/content/
This document describes Neutron for contributors of the project, and assumes
that you are already familiar with Neutron from an `end-user perspective`_.
@ -30,23 +30,27 @@ that you are already familiar with Neutron from an `end-user perspective`_.
This documentation is generated by the Sphinx toolkit and lives in the source
tree. Additional documentation on Neutron and other components of OpenStack
can be found on the `OpenStack wiki`_. The `Neutron Development wiki`_ is a very good
place to start.
can be found on the `OpenStack wiki`_ and the `Neutron section of the wiki`.
The `Neutron Development wiki`_ is also a good resource for new contributors.
.. _`OpenStack wiki`: http://wiki.openstack.org
.. _`Neutron section of the wiki`: http://wiki.openstack.org/Neutron
.. _`Neutron Development wiki`: http://wiki.openstack.org/NeutronDevelopment
Enjoy!
Development Documents
=====================
Developer Docs
==============
.. toctree::
:maxdepth: 1
devref/plugin-api
devref/index
devref/common
API Extensions
==============
Go to http://api.openstack.org for information about OpenStack Network API extensions.
Man Pages
---------