Repository: DataBiosphere/toil

Issue:
Building Sphinx docs generates warnings
```
(venv)hannes-mbpr:docs hannes$ make clean html
rm -rf _build/*
sphinx-build -b html -d _build/doctrees   . _build/html
Running Sphinx v1.3.2
making output directory...
/Users/hannes/workspace/bd2k/toil
/Users/hannes/workspace/bd2k/toil
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 6 source files that are out of date
updating environment: 6 added, 0 changed, 0 removed
reading sources... [100%] tutorial                                                                                                                                                                          
/Users/hannes/workspace/bd2k/toil/docs/essentials.rst:183: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore:4: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore.updateFile:5: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore.updateFileStream:6: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore.writeSharedFileStream:5: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore.writeSharedFileStream:8: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/jobStores/abstractJobStore.py:docstring of toil.jobStores.abstractJobStore.AbstractJobStore.writeSharedFileStream:11: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addChildFn:3: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addChildFn:3: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addChildJobFn:4: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addChildJobFn:4: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addFollowOnFn:3: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addFollowOnFn:3: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addFollowOnJobFn:4: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.addFollowOnJobFn:4: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.getRootJobs:2: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.wrapFn:3: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.wrapFn:3: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.wrapJobFn:3: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.wrapJobFn:3: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.FileStore.readGlobalFile:4: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.FileStore.readGlobalFile:16: WARNING: Field list ends without a blank line; unexpected unindent.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.FunctionWrappingJob:3: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.FunctionWrappingJob:3: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.JobFunctionWrappingJob:5: WARNING: Inline emphasis start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.JobFunctionWrappingJob:5: WARNING: Inline strong start-string without end-string.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.EncapsulatedJob:5: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.checkJobGraphAcylic:5: ERROR: Undefined substitution referenced: "V|^2). It is O(|V".
/Users/hannes/workspace/bd2k/toil/src/toil/job.py:docstring of toil.job.Job.checkJobGraphAcylic:5: ERROR: Undefined substitution referenced: "E".
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:14: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:43: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:129: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:149: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:160: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:171: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:193: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:218: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:242: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:267: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:294: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:314: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:326: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:361: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:383: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:393: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:460: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:507: ERROR: Unexpected indentation.
/Users/hannes/workspace/bd2k/toil/docs/tutorial.rst:529: ERROR: Unexpected indentation.
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorial                                                                                                                                                                           
generating indices... genindex
highlighting module code... [100%] toil.batchSystems.abstractBatchSystem                                                                                                                                    
writing additional pages... search
copying static files... WARNING: html_static_path entry u'/Users/hannes/workspace/bd2k/toil/docs/_static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 49 warnings.

Build finished. The HTML pages are in _build/html.
```



Discussion:

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -166,7 +166,7 @@ def setup(app):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
diff --git a/src/toil/job.py b/src/toil/job.py
--- a/src/toil/job.py
+++ b/src/toil/job.py
@@ -163,7 +163,7 @@ def addChildFn(self, fn, *args, **kwargs):
         """
         Adds a function as a child job.
         
-        :param fn: Function to be run as a child job with *args and **kwargs as \
+        :param fn: Function to be run as a child job with ``*args`` and ``**kwargs`` as \
         arguments to this function. See toil.job.FunctionWrappingJob for reserved \
         keyword arguments used to specify resource requirements.
         :return: The new child job that wraps fn.
@@ -175,7 +175,7 @@ def addFollowOnFn(self, fn, *args, **kwargs):
         """
         Adds a function as a follow-on job.
         
-        :param fn: Function to be run as a follow-on job with *args and **kwargs as \
+        :param fn: Function to be run as a follow-on job with ``*args`` and ``**kwargs`` as \
         arguments to this function. See toil.job.FunctionWrappingJob for reserved \
         keyword arguments used to specify resource requirements.
         :return: The new follow-on job that wraps fn.
@@ -188,7 +188,7 @@ def addChildJobFn(self, fn, *args, **kwargs):
         Adds a job function as a child job. See :class:`toil.job.JobFunctionWrappingJob`
         for a definition of a job function.
         
-        :param fn: Job function to be run as a child job with *args and **kwargs as \
+        :param fn: Job function to be run as a child job with ``*args`` and ``**kwargs`` as \
         arguments to this function. See toil.job.JobFunctionWrappingJob for reserved \
         keyword arguments used to specify resource requirements.
         :return: The new child job that wraps fn.
@@ -201,7 +201,7 @@ def addFollowOnJobFn(self, fn, *args, **kwargs):
         Add a follow-on job function. See :class:`toil.job.JobFunctionWrappingJob`
         for a definition of a job function.
         
-        :param fn: Job function to be run as a follow-on job with *args and **kwargs as \
+        :param fn: Job function to be run as a follow-on job with ``*args`` and ``**kwargs`` as \
         arguments to this function. See toil.job.JobFunctionWrappingJob for reserved \
         keyword arguments used to specify resource requirements.
         :return: The new follow-on job that wraps fn.
@@ -215,7 +215,7 @@ def wrapFn(fn, *args, **kwargs):
         Makes a Job out of a function. \
         Convenience function for constructor of :class:`toil.job.FunctionWrappingJob`.
         
-        :param fn: Function to be run with *args and **kwargs as arguments. \
+        :param fn: Function to be run with ``*args`` and ``**kwargs`` as arguments. \
         See toil.job.JobFunctionWrappingJob for reserved keyword arguments used \
         to specify resource requirements.
         :return: The new function that wraps fn.
@@ -229,7 +229,7 @@ def wrapJobFn(fn, *args, **kwargs):
         Makes a Job out of a job function. \
         Convenience function for constructor of :class:`toil.job.JobFunctionWrappingJob`.
         
-        :param fn: Job function to be run with *args and **kwargs as arguments. \
+        :param fn: Job function to be run with ``*args`` and ``**kwargs`` as arguments. \
         See toil.job.JobFunctionWrappingJob for reserved keyword arguments used \
         to specify resource requirements.
         :return: The new job function that wraps fn.
@@ -299,6 +299,7 @@ def getRootJobs(self):
         """
         :return: The roots of the connected component of jobs that contains this job. \
         A root is a job with no predecessors.
+
         :rtype : set of toil.job.Job instances
         """
         roots = set()
@@ -343,7 +344,7 @@ def checkJobGraphAcylic(self):
         an edge an "implied" edge. The augmented job graph is a job graph including \
         all the implied edges.
 
-        For a job graph G = (V, E) the algorithm is O(|V|^2). It is O(|V| + |E|) for \
+        For a job graph G = (V, E) the algorithm is ``O(|V|^2)``. It is ``O(|V| + |E|)`` for \
         a graph with no follow-ons. The former follow-on case could be improved!
         """
         #Get the root jobs
@@ -600,8 +601,8 @@ def readGlobalFile(self, fileStoreID, userPath=None, cache=True):
             """
             Get a copy of a file in the job store. 
             
-            :param string userPath: a path to the name of file to which the global \ 
-            file will be copied or hard-linked (see below). 
+            :param string userPath: a path to the name of file to which the global \
+            file will be copied or hard-linked (see below).
             
             :param boolean cache: If True will use caching (see below). Caching will \
             attempt to keep copies of files between sequences of jobs run on the same \
@@ -622,7 +623,8 @@ def readGlobalFile(self, fileStoreID, userPath=None, cache=True):
             this will result in two copies of the file on the system.
             
             :return: an absolute path to a local, temporary copy of the file keyed \
-            by fileStoreID. 
+            by fileStoreID.
+
             :rtype : string
             """
             if fileStoreID in self.filesToDelete:
@@ -1339,7 +1341,7 @@ class FunctionWrappingJob(Job):
     def __init__(self, userFunction, *args, **kwargs):
         """
         :param userFunction: The function to wrap. The userFunction will be called \
-        with the *args and **kwargs as arguments. 
+        with the ``*args`` and ``**kwargs`` as arguments.
         
         The keywords "memory", "cores", "disk", "cache" are reserved keyword arguments \
         that if specified will be used to determine the resources for the job, \
@@ -1401,6 +1403,7 @@ class EncapsulatedJob(Job):
     
     Let A be the root job of a job subgraph and B be another job we'd like to run after A
     and all its successors have completed, for this use encapsulate::
+
         A, B = A(), B() #Job A and subgraph, Job B
         A' = A.encapsulate()
         A'.addChild(B) #B will run after A and all its successors have 
diff --git a/src/toil/jobStores/abstractJobStore.py b/src/toil/jobStores/abstractJobStore.py
--- a/src/toil/jobStores/abstractJobStore.py
+++ b/src/toil/jobStores/abstractJobStore.py
@@ -61,11 +61,12 @@ class AbstractJobStore(object):
 
     def __init__(self, config=None):
         """
-        :param config: If config is not None then the
-        given configuration object will be written to the shared file "config.pickle" which can
-        later be retrieved using the readSharedFileStream. See writeConfigToStore. 
-        If this file already exists it will be overwritten. If config is None, 
+        :param config: If config is not None then the \
+        given configuration object will be written to the shared file "config.pickle" which can \
+        later be retrieved using the readSharedFileStream. See writeConfigToStore. \
+        If this file already exists it will be overwritten. If config is None, \
         the shared file "config.pickle" is assumed to exist and is retrieved. See loadConfigFromStore.
+
         """
         # Now get on with reading or writing the config
         if config is None:
@@ -398,7 +399,7 @@ def updateFile(self, jobStoreFileID, localFilePath):
         Replaces the existing version of a file in the jobStore. Throws an exception if the file
         does not exist.
 
-        :raises ConcurrentFileModificationException: if the file was modified concurrently during
+        :raises ConcurrentFileModificationException: if the file was modified concurrently during \
         an invocation of this method
         """
         raise NotImplementedError()
@@ -410,7 +411,7 @@ def updateFileStream(self, jobStoreFileID):
         which can be written to. The yielded file handle does not need to and 
         should not be closed explicitly.
 
-        :raises ConcurrentFileModificationException: if the file was modified concurrently during
+        :raises ConcurrentFileModificationException: if the file was modified concurrently during \
         an invocation of this method
         """
         raise NotImplementedError()
@@ -428,16 +429,16 @@ def updateFileStream(self, jobStoreFileID):
     @contextmanager
     def writeSharedFileStream(self, sharedFileName, isProtected=None):
         """
-        Returns a context manager yielding a writable file handle to the global file referenced
+        Returns a context manager yielding a writable file handle to the global file referenced \
         by the given name.
 
-        :param sharedFileName: A file name matching AbstractJobStore.fileNameRegex, unique within
+        :param sharedFileName: A file name matching AbstractJobStore.fileNameRegex, unique within \
         the physical storage represented by this job store
 
-        :param isProtected: True if the file must be encrypted, None if it may be encrypted or
+        :param isProtected: True if the file must be encrypted, None if it may be encrypted or \
         False if it must be stored in the clear.
 
-        :raises ConcurrentFileModificationException: if the file was modified concurrently during
+        :raises ConcurrentFileModificationException: if the file was modified concurrently during \
         an invocation of this method
         """
         raise NotImplementedError()


Test patch: