Update documentation.

Signed-off-by: Edward Z. Yang <ezyang@mit.edu>

diff --git a/doc/module/wizard.install.rst b/doc/module/wizard.install.rst
index 0322f217fd12b65326abc91478e133d3c7372f42..cec6ae407fb6bddee83599bb9ab6dae79b224fc6 100644 (file)
--- a/doc/module/wizard.install.rst
+++ b/doc/module/wizard.install.rst
@@ -4,21 +4,50 @@
 .. automodule:: wizard.install
 
 Classes
--------
-.. autoclass:: OptionParser
+----------------
+.. autoclass:: Strategy
+    :members:
+.. autoclass:: Arg
+.. autoclass:: ArgSet
+.. autoclass:: ArgHandler
     :members:
 
+Predefined classes
+------------------
+.. autoclass:: WebArgSet
+    :show-inheritance:
+.. autoclass:: MysqlArgSet
+    :show-inheritance:
+.. autoclass:: AdminArgSet
+    :show-inheritance:
+.. autoclass:: EmailArgSet
+    :show-inheritance:
+.. autoclass:: ScriptsWebStrategy
+    :members:
+    :show-inheritance:
+.. autoclass:: ScriptsMysqlStrategy
+    :members:
+    :show-inheritance:
+.. autoclass:: ScriptsEmailStrategy
+    :members:
+    :show-inheritance:
+
 Functions
 ---------
 .. autofunction:: fetch
 .. autofunction:: attr_to_option
-.. autofunction:: calculate_web
-.. autofunction:: calculate_mysql
-.. autofunction:: calculate_email
+.. autofunction:: preloads
 
 Exceptions
 ----------
 .. autoexception:: Error
 .. autoexception:: Failure
+    :show-inheritance:
+.. autoexception:: StrategyFailed
+    :show-inheritance:
 .. autoexception:: UnrecognizedPreloads
+    :show-inheritance:
+    :members:
 .. autoexception:: MissingRequiredParam
+    :show-inheritance:
+    :members:

diff --git a/wizard/install.py b/wizard/install.py
index c355601ba48db45f7c645634930e2408391ad9c4..c9e2f5bc1df6b010a3dd0becf86614defb9d4f0b 100644 (file)
--- a/wizard/install.py
+++ b/wizard/install.py
@@ -1,5 +1,5 @@
 """
-This module contains a object model for specifying "required options",
+This module contains an object model for specifying "required options",
 also known as "Args".  Whereas :class:`optparse.OptionParser` might
 normally be configured by performing a bunch of function calls, we
 generalize this configuration in order to support other types
@@ -13,9 +13,9 @@ of :class:`Arg` can be registered to the :class:`ArgHandler`, which
 manages marshalling these objects to whatever object
 is actually managing user input.  An argument is any valid Python
 variable name, usually categorized using underscores (i.e.
-admin_user); the argument capitalized and with 'WIZARD_' prepended
+admin_user); the argument capitalized and with ``WIZARD_`` prepended
 to it indicates a corresponding environment variable, i.e.
-'WIZARD_ADMIN_USER'.
+``WIZARD_ADMIN_USER``.
 
 Because autoinstallers will often have a number of themed
 arguments (i.e. MySQL credentials) that are applicable across
@@ -24,7 +24,7 @@ instances together, as well as promote reuse of these arguments.
 There are a number of precanned :class:`ArgSet` subclasses
 that serve this purpose, such as :class:`MysqlArgSet`.
 :class:`ArgHandler` also contains some convenience syntax in its
-constructor for loading :class:`ArgSet`.
+constructor for loading predefined instances of :class:`ArgSet`.
 
 Certain arguments will vary from install to install, but
 can be automatically calculated if certain assumptions about the
@@ -125,6 +125,7 @@ class ScriptsWebStrategy(Strategy):
     """Performs scripts specific guesses for web variables."""
     # XXX: THIS CODE SUCKS
     def execute(self, options):
+        """Guesses web path by splitting on web_scripts."""
         _, _, web_path = os.getcwd().partition("/web_scripts")
         if not web_path:
             raise StrategyFailed
@@ -133,11 +134,12 @@ class ScriptsWebStrategy(Strategy):
 
 class ScriptsMysqlStrategy(Strategy):
     """
-    Performs scripts specific guesses for mysql variables.  This
+    Performs scripts specific guesses for MySQL variables.  This
     may create an appropriate database for the user.
     """
     side_effects = True
     def execute(self, options):
+        """Attempts to create a database using Scripts utilities."""
         try:
             triplet = subprocess.Popen("/mit/scripts/sql/bin/get-password", stdout=subprocess.PIPE).communicate()[0].rstrip().split()
         except:
@@ -152,6 +154,7 @@ class ScriptsMysqlStrategy(Strategy):
 class ScriptsEmailStrategy(Strategy):
     """Performs script specific guess for email."""
     def execute(self, options):
+        """Guesses email using username."""
         # XXX: should double-check that you're on a scripts server
         # and fail if you're not.
         options.email = os.getenv("USER") + "@mit.edu"
@@ -161,7 +164,7 @@ class Arg(object):
     Represent a required, named argument for installation.  These
     cannot have strategies associated with them, so if you'd like
     to have a strategy associated with a single argument, create
-    set with one item in it.
+    an :class:`ArgSet` with one item in it.
     """
     #: Attribute name of the argument
     name = None
@@ -177,10 +180,10 @@ class Arg(object):
     def envname(self):
         """Name of the environment variable containing this arg."""
         return 'WIZARD_' + self.name.upper()
-    def __init__(self, name, password=False, type=None, help="XXX: UNDOCUMENTED"):
+    def __init__(self, name, password=False, type=None, help=None):
         self.name = name
         self.password = password
-        self.help = help
+        self.help = help or "UNDOCUMENTED"
         self.type = type
 
 class ArgSet(object):
@@ -262,7 +265,7 @@ class ArgHandler(object):
     """
     #: List of :class:`ArgSet` objects in schema.  The element at
     #: index 0 will always be an anonymous :class:`ArgSet` that you
-    #: can add stray :class:`Arg`s to.
+    #: can add stray instances of :class:`Arg` to.
     argsets = None
     def __init__(self, *args):
         self.argsets = [ArgSet(), WebArgSet()]
@@ -338,7 +341,7 @@ class StrategyFailed(Error):
 
 class UnrecognizedPreloads(Error):
     """You passed a preload that was not recognized."""
-    #: The preloads that were not recognized
+    #: The preloads that were not recognized.
     preloads = None
     def __init__(self, preloads):
         self.preloads = preloads

diff --git a/wizard/shell.py b/wizard/shell.py
index 7082f0142012aa0f46193c1c4a9745ba9771d15e..c7c7c3e516606a3e8aed73beabd714185df09dcd 100644 (file)
--- a/wizard/shell.py
+++ b/wizard/shell.py
@@ -182,6 +182,12 @@ class ParallelShell(Shell):
         processing.  Keyword arguments are the same as
         :meth:`Shell.callAsUser` with the additions of keyword
         arguments from :meth:`call`.
+
+    .. method:: safeCall(*args, **kwargs)
+
+        Enqueues a "safe" call for parallel processing.  Keyword
+        arguments are the same as :meth:`Shell.safeCall` with the
+        additions of keyword arguments from :meth:`call`.
     """
     def __init__(self, dry = False, max = 10):
         super(ParallelShell, self).__init__(dry=dry)