Merge lp:~javier.collado/utah/documentation_fixes into lp:utah

[Javier Collado]

Fixes for a few warnings that were printed while building the documentation.

[Max Brustkern (nuclearbob)]

Looks good to me. Is there an easy way for me to check new code for these sorts of things? The version of pep257 I have didn't seem to pick them up.

review: Approve

[Javier Collado (javier.collado)]

Yes, the fixes in this branch are not really pep257 errors, but problems
related to reStructuredText and sphinx. What I've done with this is just build
the documentation and look at the output:

$ cd docs/
$ make html
sphinx-build -b html -d build/doctrees source build/html
Making output directory...
Running Sphinx v1.1.3
loading pickled environment... not yet created
building [html]: targets for 10 source files that are out of date
updating environment: 10 added, 0 changed, 0 removed
reading sources... [100%] reference
utah/dev/utah/process.py:docstring of utah.process.pid_in_use:7: WARNING: Field list ends without a blank line; unexpected unindent.
utah/dev/utah/retry.py:docstring of utah.retry.retry:16: ERROR: Unexpected indentation.
utah/dev/utah/run.py:docstring of utah.run.ReturnCodes:1: ERROR: Unknown target name: "run".
utah/dev/utah/run.py:docstring of utah.run.common_arguments:1: ERROR: Unknown target name: "run".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] reference
writing additional files... (33 module code pages) _modules/index
 genindex py-modindex search
copying images... [100%] img/utah.jpg
copying static files... done
dumping search index... done
dumping object inventory... done
build succeeded, 4 warnings.

Build finished. The HTML pages are in build/html.

=== modified file 'utah/process.py'
--- utah/process.py	2013-04-10 15:42:26 +0000
+++ utah/process.py	2013-04-16 11:36:26 +0000
@@ -28,8 +28,9 @@
     If arg_patterns is provided then the pid's command line will be compared
     to make sure it matches an expected value.
 
-    :returns: proc object if the pid is active and optionally matches one of
-    the arg_patterns, otherwise None
+    :returns:
+        proc object if the pid is active and optionally matches one of the
+        arg_patterns, otherwise None
     :rtype: psutil.Process
 
     """

=== modified file 'utah/retry.py'
--- utah/retry.py	2013-04-03 21:17:26 +0000
+++ utah/retry.py	2013-04-16 11:36:26 +0000
@@ -33,16 +33,19 @@
     :param command: Command to be executed.
     :type command: callable
     :param args: Positional arguments to be passed to the callable.
+    :type args: tuple
     :param kwargs:
         Keyword arguments to be passed to the callable.
 
         .. note::
             There are a few keywords that are consumed by ``retry`` and not
             passed to the callable:
+
               * ``logmethod``: Preferred log method for every retry attempt
                 (``sys.stderr`` by default)
               * ``retry_timeout``: Timeout in seconds between each retry
                 attempt
+    :type kwargs: dict
 
     :returns: The value returned by the callable.
 

=== modified file 'utah/run.py'
--- utah/run.py	2013-04-11 19:09:06 +0000
+++ utah/run.py	2013-04-16 11:36:26 +0000
@@ -38,7 +38,7 @@
 # Return codes for the server
 class ReturnCodes:
 
-    """Provide standard return codes for run_ scripts."""
+    """Provide standard return codes for run\_ scripts."""
 
     SUCCESS = 0  # No problems found
     UTAH_EXCEPTION_ERROR = 1  # UTAH exception caught
@@ -65,7 +65,7 @@
 
 
 def common_arguments(parser):
-    """Centralize command line arguments for all run_ scripts.
+    """Centralize command line arguments for all run\_ scripts.
 
     :returns: argparse parser with arguments added
     :rtype: obj