Work on document structure and doc building

This patch clarifies the document structure of
doc/source/devref/development.environment.rst and adds a section about
how to build the documentation.  This patch also strips out the
redundant information in doc/README.rst, replacing it with a reference
to doc/source/devref/development.environment.rst.

Change-Id: Ia354dcbaea35b812327dac7371ea2fe9aec2b594
Closes-Bug: 1268424

doc/README.rst

@@ -1,40 +1,5 @@
 OpenStack Nova Documentation README
 ===================================
-Included documents:
 
-- developer reference guide(devref)
+See the "Building the Documentation" section of
-- man pages
+doc/source/devref/development.environment.rst.
-
-Dependencies
-------------
-Building this documentation can be done in a regular Nova development
-environment, such as the virtualenv created by ``run_tests.sh`` or
-``tools/install_venv.py``.  A leaner but sufficient environment can be
-created by starting with one that is suitable for running Nova (such
-as the one created by DevStack) and then using pip to install
-oslosphinx.
-
-Building the docs
------------------
-From the root nova directory::
-
-  python setup.py build_sphinx
-
-Building just the man pages
----------------------------
-from the root nova directory::
-
-  python setup.py build_sphinx -b man
-
-
-Installing the man pages
--------------------------
-After building the man pages, they can be found in ``doc/build/man/``.
-You can install the man page onto your system by following the following steps:
-
-Example for ``nova-scheduler``::
-
-  mkdir /usr/local/man/man1
-  install -g 0 -o 0 -m 0644 doc/build/man/nova-scheduler.1  /usr/local/man/man1/nova-scheduler.1
-  gzip /usr/local/man/man1/nova-scheduler.1
-  man nova-scheduler

doc/source/devref/development.environment.rst

@@ -15,40 +15,64 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Setting Up a Development Environment
+==============================================
-====================================
+Setting Up and Using a Development Environment
+==============================================
 
-This page describes how to setup a working Python development
+This page describes how to setup and use a working Python development
 environment that can be used in developing nova on Ubuntu, Fedora or
-Mac OS X. These instructions assume you're already familiar with
+Mac OS X. These instructions assume you're already familiar with git.
-git.
 
-Following these instructions will allow you to run the nova unit
+Following these instructions will allow you to build the documentation
-tests. If you want to be able to run nova (i.e., launch VM instances),
+and run the nova unit tests. If you want to be able to run nova (i.e.,
-you will also need to install libvirt and at least one of the
+launch VM instances), you will also need to --- either manually or by
-`supported hypervisors`_. Running nova is currently only supported on
+letting DevStack do it for you --- install libvirt and at least one of
-Linux, although you can run the unit tests on Mac OS X.
+the `supported hypervisors`_. Running nova is currently only supported
+on Linux, although you can run the unit tests on Mac OS X.
 
 .. _supported hypervisors: http://wiki.openstack.org/HypervisorSupportMatrix
 
-Virtual environments
---------------------
 
-Nova development uses a set of shell scripts in DevStack. Virtual
+Setup
-environments with venv are also available with the source code.
+=====
+
+There are two ways to create a development environment: using
+DevStack, or explicitly installing and cloning just what you need.
+
+
+Using DevStack
+--------------
 
 The easiest way to build a fully functional development environment is
-with DevStack. Create a machine (such as a VM or Vagrant box) running a
+with DevStack. DevStack will hack your machine pretty hard, and so we
-distribution supported by DevStack and install DevStack there. For
+recommend that you create a machine (such as a VM or Vagrant box)
-example, there is a Vagrant script for DevStack at http://git.openstack.org/cgit/openstack-dev/devstack-vagrant/.
+running a distribution supported by DevStack and run DevStack
+there. For example, there is a Vagrant script for DevStack at
+http://git.openstack.org/cgit/openstack-dev/devstack-vagrant/ .
 
- .. note::
+Include the line
 
-    If you prefer not to use devstack, you can still check out source code on your local
+.. code-block:: bash
-    machine and develop from there.
+
+  INSTALL_TESTONLY_PACKAGES=True
+
+in the ``localrc`` file you use to control DevStack.  This will cause
+DevStack to install what you need for testing and documentation
+building as well as running the system.
+
+Explicit Install/Clone
+----------------------
+
+DevStack installs a complete OpenStack environment.  Alternatively,
+you can explicitly install and clone just what you need for Nova
+development.
+
+The first step of this process is to install the system (not Python)
+packages that are required.  Following are instructions on how to do
+this on Linux and on the Mac.
 
 Linux Systems
--------------
+`````````````
 
 .. note::
 
@@ -77,7 +101,7 @@ On Fedora-based distributions (e.g., Fedora/RHEL/CentOS/Scientific Linux)::
 
 
 Mac OS X Systems
-----------------
+````````````````
 
 Install virtualenv::
 
@@ -96,21 +120,74 @@ or Mac OS X 10.7 (OpenSSL 0.9.8r) works fine with nova.
 
 
 Getting the code
-----------------
+````````````````
+
+Once you have the prerequisite system packages installed, the next
+step is to clone the code.
+
 Grab the code from GitHub::
 
     git clone https://github.com/openstack/nova.git
     cd nova
 
 
+Building the Documentation
+==========================
+
+To do a full documentation build, issue the following command while
+the nova directory is current.
+
+.. code-block:: bash
+
+  tox -edocs
+
+That will create a Python virtual environment, install the needed
+Python prerequisites in that environment, and build all the
+documentation in that environment.
+
+The following variant will do the first two steps but not build any
+documentation.
+
+.. code-block:: bash
+
+  tox --notest -edocs
+
+The virtual environment built by ``tox`` for documentation building
+will be found in ``.tox/docs``.  You can enter that virtual
+environment in the usual way, as follows.
+
+.. code-block:: bash
+
+  source .tox/docs/bin/activate
+
+To build just the man pages, enter that virtual environment and issue
+the following command while the nova directory is current.
+
+.. code-block:: bash
+
+  python setup.py build_sphinx -b man
+
+After building the man pages, they can be found in ``doc/build/man/``.
+A sufficiently authorized user can install the man page onto the
+system by following steps like the following, which are for the
+``nova-scheduler`` man page.
+
+.. code-block:: bash
+
+  mkdir /usr/local/man/man1
+  install -g 0 -o 0 -m 0644 doc/build/man/nova-scheduler.1  /usr/local/man/man1/nova-scheduler.1
+  gzip /usr/local/man/man1/nova-scheduler.1
+  man nova-scheduler
+
+
 Running unit tests
-------------------
+==================
 
 See :doc:`unit_tests` for details.
 
 
 Using a remote debugger
------------------------
+=======================
 
 Some modern IDE such as pycharm (commercial) or Eclipse (open source) support remote debugging.  In order to run nova with remote debugging, start the nova process
 with the following parameters
@@ -124,7 +201,7 @@ For Eclipse - http://pydev.org/manual_adv_remote_debugger.html
 More detailed instructions are located here - http://novaremotedebug.blogspot.com
 
 Using fake computes for tests
------------------------------
+=============================
 
 The number of instances supported by fake computes is not limited by physical
 constraints. It allows you to perform stress tests on a deployment with few
@@ -144,7 +221,7 @@ Fake computes can be used for testing Nova itself but also applications on top
 of it.
 
 Contributing Your Work
-----------------------
+======================
 
 Once your work is complete you may wish to contribute it to the project. 
 Refer to HowToContribute_ for information.