Add "optional" to parameter docstrings. (#763)

* Document optional parameters.

* Remove indication of default values when no default exists.

* Add optional parameter docstrings to synced collections.

signac/contrib/_searchindexer.py

@@ -98,7 +98,7 @@ def get(self, key, default=None):
         ----------
         key : str, float
             The key to get the value.
-        default :
+        default : object, optional
             Default value if type of key is not float (Default value = None).
 
         Returns
@@ -380,7 +380,7 @@ def _find_result(self, expr):
         Parameters
         ----------
         expr : dict
-            The filter of expressions to match (Default value = None).
+            The filter of expressions to match.
 
         Returns
         -------
@@ -471,7 +471,7 @@ def find(self, filter_=None):
 
         Parameters
         ----------
-        filter_ : dict
+        filter_ : dict, optional
             The filter of expressions to match (Default value = None).
 
         Returns

signac/contrib/filterparse.py

@@ -144,7 +144,7 @@ def _parse_single(key, value=None):
     ----------
     key : str
         The filter key.
-    value :
+    value : object, optional
         The filter value. If None, the filter returns
         True if the provided key exists (Default value = None).
 

signac/contrib/import_export.py

@@ -46,9 +46,9 @@ def _make_schema_based_path_function(jobs, exclude_keys=None, delimiter_nested="
     ----------
     jobs : iterable of :class:`~signac.contrib.job.Job`
         A sequence of jobs (instances of :class:`~signac.contrib.job.Job`).
-    exclude_keys : sequence[str]
+    exclude_keys : sequence[str], optional
         A sequence of keys to exclude (Default value = None).
-    delimiter_nested : str
+    delimiter_nested : str, optional
         Delimiter used for nesting keys (Default value = '.').
 
     Returns
@@ -87,7 +87,7 @@ def path(job, sep=None):
         ----------
         job : :class:`~signac.contrib.job.Job`
             An instance of :class:`~signac.contrib.job.Job`.
-        sep : str
+        sep : str, optional
             (Default value = None)
 
         Returns
@@ -322,7 +322,7 @@ def _export_jobs(jobs, path, copytree):
     jobs : iterable of :class:`~signac.contrib.job.Job`
         A sequence of jobs (instance of :class:`~signac.contrib.job.Job`).
     path : str or callable
-        The path (function) used to structure the exported data space (Default value = None).
+        The path (function) used to structure the exported data space.
     copytree : callable
         The function used for copying directory tree structures.
 
@@ -366,9 +366,9 @@ def export_to_directory(jobs, target, path=None, copytree=None):
         A sequence of jobs (instances of :class:`~signac.contrib.job.Job`).
     target : str
         A path to a directory to export to. The directory can not already exist.
-    path : str or callable
+    path : str or callable, optional
         The path (function) used to structure the exported data space (Default value = None).
-    copytree : callable
+    copytree : callable, optional
         The function used for copying directory tree structures. Uses
         :func:`shutil.copytree` if ``None`` (Default value = None). The function
         requires that the target is a directory.
@@ -409,7 +409,7 @@ def export_to_tarfile(jobs, tarfile, path=None):
         A sequence of jobs (instances of :class:`~signac.contrib.job.Job`).
     tarfile : :class:`tarfile.TarFile`
         An instance of :class:`tarfile.TarFile`.
-    path : str or callable
+    path : str or callable, optional
         The path (function) used to structure the exported data space (Default value = None).
 
     Returns
@@ -430,7 +430,7 @@ def export_to_zipfile(jobs, zipfile, path=None):
         A sequence of jobs (instances of :class:`~signac.contrib.job.Job`).
     zipfile : :class:`zipfile.ZipFile`
         An instance of :class:`zipfile.ZipFile`.
-    path : str or callable
+    path : str or callable, optional
         The path (function) used to structure the exported data space (Default value = None).
 
     Returns
@@ -472,7 +472,7 @@ def export_jobs(jobs, target, path=None, copytree=None):
         A sequence of jobs(instance of :class:`~signac.contrib.job.Job`).
     target : str
         A path to a directory or archive file to export to.
-    path : str or callable
+    path : str or callable, optional
         The path (function) used to structure the exported data space. (Default value = None)
     copytree : callable
         The function used for copying of directory tree
@@ -1180,7 +1180,7 @@ def _prepare_import_into_project(origin, project, schema=None):
         Path to current working directory.
     project : :class:`~signac.Project`
         The project to import the data into.
-    schema : str or callable
+    schema : str or callable, optional
         An optional schema function, which is either a string or a function that accepts a
         path as its first and only argument and returns the corresponding state point as dict
         (Default value = None).
@@ -1246,7 +1246,7 @@ def import_into_project(origin, project, schema=None, copytree=None):
         a directory, a zipfile, or a tarball archive.
     project : :class:`~signac.Project`
         The project to import the data into.
-    schema : str or callable
+    schema : str or callable, optional
         An optional schema function, which is either a string or a function that accepts a
         path as its first and only argument and returns the corresponding state point as dict
         (Default value = None).

signac/contrib/job.py

@@ -232,9 +232,9 @@ class Job:
     ----------
     project : :class:`~signac.Project`
         Project handle.
-    statepoint : dict
+    statepoint : dict, optional
         State point for the job. (Default value = None)
-    id_ : str
+    id_ : str, optional
         The job identifier. (Default value = None)
 
     """
@@ -618,7 +618,7 @@ def init(self, force=False):
 
         Parameters
         ----------
-        force : bool
+        force : bool, optional
             Overwrite any existing state point files, e.g., to repair them if
             they got corrupted (Default value = False).
 
@@ -786,21 +786,21 @@ def sync(self, other, strategy=None, exclude=None, doc_sync=None, **kwargs):
         ----------
         other : Job
             The other job to synchronize from.
-        strategy :
+        strategy : callable, optional
             A synchronization strategy for file conflicts. If no strategy is provided, a
             :class:`~signac.errors.SyncConflict` exception will be raised upon conflict
             (Default value = None).
-        exclude : str
-            An filename exclude pattern. All files matching this pattern will be
+        exclude : str, optional
+            A filename exclude pattern. All files matching this pattern will be
             excluded from synchronization (Default value = None).
-        doc_sync :
+        doc_sync : attribute or callable from :py:class:`~signac.sync.DocSync`, optional
             A synchronization strategy for document keys. If this argument is None, by default
-            no keys will be synchronized upon conflict.
-        dry_run :
+            no keys will be synchronized upon conflict (Default value = None).
+        dry_run : bool, optional
             If True, do not actually perform the synchronization.
         \*\*kwargs :
-            Extra keyword arguments will be forward to the :meth:`~signac.sync.sync_jobs`
-            function which actually excutes the synchronization operation.
+            Extra keyword arguments will be forwarded to the :meth:`~signac.sync.sync_jobs`
+            function which actually executes the synchronization operation.
 
         Raises
         ------

signac/contrib/linked_view.py

@@ -21,12 +21,12 @@ def create_linked_view(project, prefix=None, job_ids=None, path=None):
     ----------
     project : signac.Project
         Project handle.
-    prefix : str
+    prefix : str, optional
         The path where the linked view will be created or updated (Default value = None).
-    job_ids : iterable
+    job_ids : iterable, optional
         If None (the default), create the view for the complete data space,
         otherwise only for this iterable of job ids.
-    path :
+    path : str or callable, optional
         The path (function) used to structure the linked data space (Default value = None).
 
     Returns
@@ -304,8 +304,8 @@ def _find_dead_branches(root, branch=None):
     ----------
     root : :class:`~signac.contrib.linked_view._Node`
         Root node.
-    branch : list
-        The current list of branches that has been collected,
+    branch : list, optional
+        The current list of branches that have been collected,
         used in recursive calls to build up the branches starting
         at the root (Default value = None).
 

signac/contrib/project.py

@@ -441,9 +441,9 @@ def open_job(self, statepoint=None, id=None):
 
         Parameters
         ----------
-        statepoint : dict
+        statepoint : dict, optional
             The job's unique set of state point parameters (Default value = None).
-        id : str
+        id : str, optional
             The job id (Default value = None).
 
         Returns
@@ -572,10 +572,10 @@ def detect_schema(self, exclude_const=False, subset=None):
 
         Parameters
         ----------
-        exclude_const : bool
+        exclude_const : bool, optional
             Exclude all state point keys that are shared by all jobs within this project
             (Default value = False).
-        subset :
+        subset : sequence[Job or str], optional
             A sequence of jobs or job ids specifying a subset over which the state point
             schema should be detected (Default value = None).
 
@@ -609,7 +609,7 @@ def _find_job_ids(self, filter=None):
 
         Parameters
         ----------
-        filter : Mapping
+        filter : Mapping, optional
             A mapping of key-value pairs used for the query (Default value =
             None).
 
@@ -647,7 +647,7 @@ def find_jobs(self, filter=None):
 
         Parameters
         ----------
-        filter : Mapping
+        filter : Mapping, optional
             A mapping of key-value pairs used for the query (Default value =
             None).
 
@@ -707,11 +707,11 @@ def groupby(self, key=None, default=None):
 
         Parameters
         ----------
-        key : str, iterable, or callable
+        key : str, iterable, or callable, optional
             The state point grouping parameter(s) passed as a string,
             iterable of strings, or a callable that will be passed one
             argument, the job (Default value = None).
-        default :
+        default : object, optional
             A default value to be used when a given state point key is not
             present. The value must be sortable and is only used if not None
             (Default value = None).
@@ -874,12 +874,12 @@ def create_linked_view(self, prefix=None, job_ids=None, path=None):
 
         Parameters
         ----------
-        prefix : str
+        prefix : str, optional
             The path where the linked view will be created or updated (Default value = None).
-        job_ids : iterable
+        job_ids : iterable, optional
             If None (the default), create the view for the complete data space,
             otherwise only for this iterable of job ids.
-        path :
+        path : str or callable, optional
             The path (function) used to structure the linked data space (Default value = None).
 
         Returns
@@ -1043,12 +1043,12 @@ def export_to(self, target, path=None, copytree=None):
 
         Parameters
         ----------
-        target :
+        target : str
             A path to a directory to export to. The target can not already exist.
             Besides directories, possible targets are tar files (`.tar`), gzipped tar files
             (`.tar.gz`), zip files (`.zip`), bzip2-compressed files (`.bz2`),
             and xz-compressed files (`.xz`).
-        path :
+        path : str or callable, optional
             The path (function) used to structure the exported data space.
             This argument must either be a callable which returns a path (str) as a function
             of `job`, a string where fields are replaced using the job-state point dictionary,
@@ -1102,14 +1102,14 @@ def import_from(self, origin=None, schema=None, sync=None, copytree=None):
 
         Parameters
         ----------
-        origin :
+        origin : str, optional
             The path to the data space origin, which is to be imported. This may be a path to
             a directory, a zip file, or a tarball archive (Default value = None).
-        schema :
+        schema : callable, optional
             An optional schema function, which is either a string or a function that accepts a
             path as its first and only argument and returns the corresponding state point as dict.
             (Default value = None).
-        sync :
+        sync : bool or dict, optional
             If ``True``, the project will be synchronized with the imported data space. If a
             dict of keyword arguments is provided, the arguments will be used for
             :meth:`~signac.Project.sync` (Default value = None).
@@ -1175,7 +1175,7 @@ def repair(self, job_ids=None):
 
         Parameters
         ----------
-        job_ids :
+        job_ids : iterable[str], optional
             An iterable of job ids that should get repaired. Defaults to all jobs.
 
         Raises
@@ -1245,7 +1245,7 @@ def _build_index(self, include_job_document=False):
 
         Parameters
         ----------
-        include_job_document : bool
+        include_job_document : bool, optional
             Whether to include the job document in the index (Default value =
             False).
 
@@ -1383,7 +1383,7 @@ def temporary_project(self, dir=None):
 
         Parameters
         ----------
-        dir : str
+        dir : str, optional
             Optionally specify where the temporary project directory is to be
             created. Defaults to the project's workspace directory.
 
@@ -1555,7 +1555,7 @@ def TemporaryProject(cls=None, **kwargs):
 
     Parameters
     ----------
-    cls :
+    cls : object, optional
         The class of the temporary project.
         Defaults to :class:`~signac.Project`.
     \*\*kwargs :
@@ -1702,11 +1702,12 @@ def groupby(self, key=None, default=None):
 
         Parameters
         ----------
-        key : str, iterable, or callable
+        key : str, iterable, or callable, optional
             The state point grouping parameter(s) passed as a string,
             iterable of strings, or a callable that will be passed one
-            argument, the job (Default value = None).
-        default :
+            argument, the job. If None, the job id is used (Default value =
+            None).
+        default : object, optional
             A default value to be used when a given state point key is not
             present. The value must be sortable and is only used if not None
             (Default value = None).
@@ -1801,7 +1802,7 @@ def keyfunction(job):
         elif key is None:
             # Must return a type that can be ordered with <, >
             def keyfunction(job):
-                return str(job)
+                return job.id
 
         else:
             # Pass the job document to a callable

signac/contrib/schema.py

@@ -251,7 +251,7 @@ def difference(self, other, ignore_values=False):
 
         Parameters
         ----------
-        ignore_values : bool
+        ignore_values : bool, optional
             Ignore if the value (range) of a specific keys differ,
             only return missing keys (Default value = False).
         other : :class:`~ProjectSchema`