doc/bettter document update and reset statepoint (#444)

* grammar fix * explaing update_statepoint without using the word update * grammar fix * noting that update_statepoint with overwrite=True is reset_statepoint * explaing reset_statetpoint without the word reset * add links to main signac-docs * add noqa for long line url * move noqa to end of docstring * expand phrase into sentence from code review Co-authored-by: Bradley Dice <[email protected]> * improve wording of overwrite argument docstring * fix whitespace * apply documentation changes to deprecated equivalent methods * suggestions from code review * Update docstring parameters. * Update docstrings. * Add missing statement. * Fix all Sphinx references to errors, add missing errors to public namespace. Co-authored-by: Bradley Dice <[email protected]> Co-authored-by: Vyas Ramasubramani <[email protected]>
glotzerlab · Jan 23, 2021 · ec58809 · ec58809
1 parent ed99e25
commit ec58809
Show file tree

Hide file tree

Showing 6 changed files with 65 additions and 39 deletions.
diff --git a/signac/contrib/collection.py b/signac/contrib/collection.py
@@ -192,7 +192,7 @@ def _build_index(docs, key, primary_key):
 
     Raises
     ------
-    InvalidKeyError
+    :class:`~signac.errors.InvalidKeyError`
         The document contains invalid keys.
 
     """

diff --git a/signac/contrib/import_export.py b/signac/contrib/import_export.py
@@ -646,7 +646,7 @@ def _check(path):
 
         Raises
         ------
-        StatepointParsingError
+        :class:`~signac.errors.StatepointParsingError`
             If identified state point conflicts with state point in job manifest file.
 
         """
@@ -817,7 +817,7 @@ def _analyze_directory_for_import(root, project, schema):
     ------
     TypeError
         If the schema given is not None, callable, or a string.
-    StatepointParsingError
+    :class:`~signac.errors.StatepointParsingError`
         If the jobs identified with the given schema function are not unique.
 
     """
@@ -910,9 +910,9 @@ def _analyze_zipfile_for_import(zipfile, project, schema):
     ------
     TypeError
         If the schema provided is not None, callable, or a string.
-    DestinationExistsError
+    :class:`~signac.errors.DestinationExistsError`
         If a job is already initialized.
-    StatepointParsingError
+    :class:`~signac.errors.StatepointParsingError`
         If the jobs identified with the given schema function are not unique.
 
     """
@@ -1055,9 +1055,9 @@ def _analyze_tarfile_for_import(tarfile, project, schema, tmpdir):
     ------
     TypeError
         If the schema given is not None, callable, or a string.
-    DestinationExistsError
+    :class:`~signac.errors.DestinationExistsError`
         If a job is already initialized.
-    StatepointParsingError
+    :class:`~signac.errors.StatepointParsingError`
         If the jobs identified with the given schema function are not unique.
     AssertionError
         If ``tmpdir`` given is not a directory.

diff --git a/signac/contrib/job.py b/signac/contrib/job.py
@@ -190,7 +190,12 @@ def ws(self):
         return self.workspace()
 
     def reset_statepoint(self, new_statepoint):
-        """Reset the state point of this job.
+        """Overwrite the state point of this job while preserving job data.
+
+        This method will change the job id if the state point has been altered.
+
+        For more information, see
+        `Modifying the State Point <https://docs.signac.io/en/latest/jobs.html#modifying-the-state-point>`_.
 
         .. danger::
 
@@ -203,7 +208,7 @@ def reset_statepoint(self, new_statepoint):
         new_statepoint : dict
             The job's new state point.
 
-        """
+        """  # noqa: E501
         dst = self._project.open_job(new_statepoint)
         if dst == self:
             return
@@ -249,7 +254,15 @@ def _reset_sp(self, new_statepoint=None):
         self.reset_statepoint(new_statepoint)
 
     def update_statepoint(self, update, overwrite=False):
-        """Update the state point of this job.
+        """Change the state point of this job while preserving job data.
+
+        By default, this method will not change existing parameters of the
+        state point of the job.
+
+        This method will change the job id if the state point has been altered.
+
+        For more information, see
+        `Modifying the State Point <https://docs.signac.io/en/latest/jobs.html#modifying-the-state-point>`_.
 
         .. warning::
 
@@ -261,22 +274,23 @@ def update_statepoint(self, update, overwrite=False):
         ----------
         update : dict
             A mapping used for the state point update.
-        overwrite :
-            Set to true, to ignore whether this update overwrites parameters,
-            which are currently part of the job's state point.
-            Use with caution! (Default value = False)
+        overwrite : bool, optional
+            If True, this method will set all existing and new parameters
+            to a job's statepoint, making it equivalent to
+            :meth:`~.reset_statepoint`. Use with caution!
+            (Default value = False).
 
         Raises
         ------
         KeyError
             If the update contains keys, which are already part of the job's
             state point and overwrite is False.
-        DestinationExistsError
+        :class:`~signac.errors.DestinationExistsError`
             If a job associated with the new state point is already initialized.
         OSError
             If the move failed due to an unknown system related error.
 
-        """
+        """  # noqa: E501
         statepoint = self.statepoint()
         if not overwrite:
             for key, value in update.items():
@@ -295,7 +309,7 @@ def _read_manifest(self):
 
         Raises
         ------
-        JobsCorruptedError
+        :class:`~signac.errors.JobsCorruptedError`
             If an error occurs while parsing the state point manifest.
         OSError
             If an error occurs while reading the state point manifest.
@@ -567,7 +581,7 @@ def _check_manifest(self):
 
         Raises
         ------
-        JobsCorruptedError
+        :class:`~signac.errors.JobsCorruptedError`
             If the manifest hash is not equal to the job id.
 
         """
@@ -743,7 +757,7 @@ def sync(self, other, strategy=None, exclude=None, doc_sync=None, **kwargs):
 
         Raises
         ------
-        FileSyncConflict
+        :class:`~signac.errors.FileSyncConflict`
             In case that a file synchronization results in a conflict.
 
         """

diff --git a/signac/contrib/project.py b/signac/contrib/project.py
@@ -1274,7 +1274,7 @@ def _get_statepoint(self, job_id, fn=None):
         ------
         KeyError
             If the state point associated with job_id could not be found.
-        JobsCorruptedError
+        :class:`signac.errors.JobsCorruptedError`
             If the state point manifest file corresponding to job_id is
             inaccessible or corrupted.
 
@@ -1346,7 +1346,7 @@ def get_statepoint(self, jobid, fn=None):
         ------
         KeyError
             If the state point associated with jobid could not be found.
-        JobsCorruptedError
+        :class:`signac.errors.JobsCorruptedError`
             If the state point manifest file corresponding to jobid is
             inaccessible or corrupted.
 
@@ -1430,7 +1430,9 @@ def create_linked_view(self, prefix=None, job_ids=None, index=None, path=None):
         details="Use job.reset_statepoint() instead.",
     )
     def reset_statepoint(self, job, new_statepoint):
-        """Reset the state point of job.
+        """Overwrite the state point of this job while preserving job data.
+
+        This method will change the job id if the state point has been altered.
 
         .. danger::
 
@@ -1462,7 +1464,12 @@ def reset_statepoint(self, job, new_statepoint):
         details="Use job.update_statepoint() instead.",
     )
     def update_statepoint(self, job, update, overwrite=False):
-        """Update the state point of this job.
+        """Change the state point of this job while preserving job data.
+
+        By default, this method will not change existing parameters of the
+        state point of the job.
+
+        This method will change the job id if the state point has been altered.
 
         .. warning::
 
@@ -1476,9 +1483,10 @@ def update_statepoint(self, job, update, overwrite=False):
             The job whose state point shall be updated.
         update : mapping
             A mapping used for the state point update.
-        overwrite :
-            Set to true to ignore whether this update overwrites parameters,
-            which are currently part of the job's state point. Use with caution!
+        overwrite : bool, optional
+            If True, this method will set all existing and new parameters
+            to a job's statepoint, making it equivalent to
+            :meth:`~.reset_statepoint`. Use with caution!
             (Default value = False).
 
         Raises
@@ -1745,7 +1753,7 @@ def check(self):
 
         Raises
         ------
-        JobsCorruptedError
+        :class:`signac.errors.JobsCorruptedError`
             When one or more jobs are identified as corrupted.
 
         """
@@ -1785,7 +1793,7 @@ def repair(self, fn_statepoints=None, index=None, job_ids=None):
 
         Raises
         ------
-        JobsCorruptedError
+        :class:`signac.errors.JobsCorruptedError`
             When one or more corrupted job could not be repaired.
 
         """

diff --git a/signac/errors.py b/signac/errors.py
@@ -12,6 +12,8 @@
     DestinationExistsError,
     IncompatibleSchemaVersion,
     JobsCorruptedError,
+    StatepointParsingError,
+    WorkspaceError,
 )
 from .core.errors import Error
 from .core.jsondict import BufferedFileError, BufferException
@@ -65,19 +67,21 @@ class KeyTypeError(TypeError):
 
 
 __all__ = [
-    "Error",
+    "AuthenticationError",
     "BufferException",
     "BufferedFileError",
     "ConfigError",
-    "AuthenticationError",
+    "DestinationExistsError",
+    "DocumentSyncConflict",
+    "Error",
     "ExportError",
     "FetchError",
-    "DestinationExistsError",
-    "JobsCorruptedError",
-    "IncompatibleSchemaVersion",
-    "SyncConflict",
     "FileSyncConflict",
-    "DocumentSyncConflict",
-    "SchemaSyncConflict",
+    "IncompatibleSchemaVersion",
     "InvalidKeyError",
+    "JobsCorruptedError",
+    "SchemaSyncConflict",
+    "StatepointParsingError",
+    "SyncConflict",
+    "WorkspaceError",
 ]
diff --git a/signac/sync.py b/signac/sync.py
@@ -483,14 +483,14 @@ def sync_projects(
 
     Raises
     ------
-    DocumentSyncConflict
+    :class:`~signac.errors.DocumentSyncConflict`
         If there are conflicting keys within the project or job documents that
         cannot be resolved with the given strategy or if there is no strategy
         provided.
-    FileSyncConflict
+    :class:`~signac.errors.FileSyncConflict`
         If there are differing files that cannot be resolved with the given
         strategy or if no strategy is provided.
-    SchemaSyncConflict
+    :class:`~signac.errors.SchemaSyncConflict`
         In case that the check_schema argument is True and the detected state
         point schema of this and the other project differ.
-Original file line number
+Diff line change
@@ Expand Up / @@ -192,7 +192,7 @@ def _build_index(docs, key, primary_key): @@
         Raises
         ------
-        InvalidKeyError
+        :class:`~signac.errors.InvalidKeyError`
             The document contains invalid keys.
         """
@@ Expand Down @@