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

diff --git a/doc/source/devref/development.environment.rst b/doc/source/devref/development.environment.rst
new file mode 100644 (file)
index 0000000..ff1471a
--- /dev/null
+++ b/doc/source/devref/development.environment.rst
@@ -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

diff --git a/doc/source/devref/index.rst b/doc/source/devref/index.rst
index bf0a005a611e71d67b6f914dab129938410fd75d..e06d580e320fd6273912d5c35eaad4cc013748d5 100644 (file)
--- a/doc/source/devref/index.rst
+++ b/doc/source/devref/index.rst
@@ -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`

diff --git a/doc/source/index.rst b/doc/source/index.rst
index 3e253ae5d2ad01ae31964115c6d2d3f376b26821..777dee8ee61cce73957af96175377a1d03444759 100644 (file)
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -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
 ---------