Finish initial docs

Finish the initial sections defined in the documentation index.
Add sphinxcontrib-programoutput to document command line utils.
Add py27 to the list of default tox targets.

Change-Id: I254534032e0706e410647b023249fe3af4f3a35f

doc/source/conf.py

@@ -25,7 +25,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = [ 'sphinxcontrib.blockdiag', 'sphinxcontrib.programoutput' ]
+extensions = [ 'sphinxcontrib.programoutput' ]
 #extensions = ['sphinx.ext.intersphinx']
 #intersphinx_mapping = {'python': ('http://docs.python.org/2.7', None)}
 

doc/source/configuration.rst

@@ -206,7 +206,7 @@ targets
 
 Lists the Jenkins masters to which Nodepool should attach nodes after
 they are created.  Nodes of each label will be evenly distributed
-across all of the targets which are on-line.
+across all of the targets which are on-line::
 
   targets:
     - name: jenkins1

doc/source/operation.rst

@@ -0,0 +1,73 @@
+.. _operation:
+
+Operation
+=========
+
+Nodepool generally runs as a daemon under the command ``nodepoold``.
+Once started, it will frequently re-read the configuration file and
+make any changes necessary (such as adding or removing a provider, or
+altering image or quota configuration).  If any needed images are
+missing, it will immediately begin trying to build those images.
+Periodically (once a day by default but configurable in the ``cron:``
+section of the config file) it will attempt to create new versions of
+each image.
+
+If a new image creation is successful, it will immediately start using
+it when launching nodes (Nodepool always uses the most recent image in
+the ``ready`` state).  Nodepool will delete images that are older than
+8 hours if they are not the most recent or second most recent
+``ready`` images.  In other words, Nodepool will always make sure that
+in addition to the current image, it keeps the previous image around.
+This way if you find that a newly created image is problematic, you
+may simply delete it and Nodepool will revert to using the previous
+image.
+
+Command Line Tools
+==================
+
+Usage
+-----
+The general options that apply to all subcommands are:
+
+.. program-output:: nodepool --help
+
+The following subcommands deal with nodepool images:
+
+image-list
+^^^^^^^^^^
+.. program-output:: nodepool image-list --help
+
+image-update
+^^^^^^^^^^^^
+.. program-output:: nodepool image-update --help
+
+image-delete
+^^^^^^^^^^^^
+.. program-output:: nodepool image-delete --help
+
+
+The following subcommands deal with nodepool nodes:
+
+list
+^^^^
+.. program-output:: nodepool list --help
+
+hold
+^^^^
+.. program-output:: nodepool hold --help
+
+delete
+^^^^^^
+.. program-output:: nodepool delete --help
+
+If Nodepool's database gets out of sync with reality, the following
+commands can help identify compute instances or images that are
+unknown to Nodepool:
+
+alien-list
+^^^^^^^^^^
+.. program-output:: nodepool alien-list --help
+
+alien-image-list
+^^^^^^^^^^^^^^^^
+.. program-output:: nodepool alien-image-list --help

doc/source/scripts.rst

@@ -1,6 +1,6 @@
 .. _scripts:
 
-Node Prep Scritps
+Node Prep Scripts
 =================
 
 Nodepool requires the specification of a script directory
@@ -8,3 +8,13 @@ Nodepool requires the specification of a script directory
 machine for the purpose of creating a snapshot image, all of the files
 within this directory will be copied to the virtual machine so they
 are available for use by the setup script.
+
+At various points in the image and node creation processes, these
+scripts may be invoked by nodepool.  See :ref:`configuration` for
+details.
+
+Any environment variables present in the nodepool daemon environment
+that begin with ``NODEPOOL_`` will be set in the calling environment
+for the script.  This is useful during testing to alter script
+behavior, for instance, to add a local ssh key that would not
+otherwise be set in production.

test-requirements.txt

@@ -2,6 +2,7 @@
 hacking>=0.8,<0.9
 coverage
 sphinx>=1.1.2,<1.2
+sphinxcontrib-programoutput
 docutils==0.9.1
 discover
 fixtures>=0.3.12

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = pep8
+envlist = pep8, py27
 
 [testenv]
 # Set STATSD env variables so that statsd code paths are tested.