Fix docs

.github/workflows/apptainer-build-deploy.yml

@@ -25,7 +25,7 @@ jobs:
       contents: write
 
     container:
-      image: quay.io/singularity/singularity:v3.8.1
+      image: apptainer/apptainer:1.2.5
       options: --privileged
 
     steps:

.github/workflows/docs.yml

@@ -3,6 +3,7 @@ name: Release Documentation
 permissions: write-all
 
 on:
+  pull_request:
   push:
     branches: [main]
   workflow_dispatch:
@@ -25,7 +26,7 @@ jobs:
           pixi-version: v0.62.2
           locked: true
           cache: true
-          cache-write: ${{ github.ref == 'refs/heads/main' }}
+          cache-write: false
           environments: dev
 
       - name: Build Docs
@@ -35,6 +36,7 @@ jobs:
 
       - name: deploy
         uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e
+        if: startsWith(github.ref, 'refs/tags/v')
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./docs/_build/html

.github/workflows/super_linter.yml

@@ -48,6 +48,7 @@ jobs:
           VALIDATE_PYTHON_PYINK: false
           VALIDATE_PYTHON_PYLINT: false
           VALIDATE_PYTHON_RUFF: false
+          VALIDATE_PYTHON_RUFF_FORMAT: false
           VALIDATE_SPELL_CODESPELL: false
           VALIDATE_YAML: false
           VALIDATE_YAML_PRETTIER: false

docs/source/api.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. autosummary::
    :toctree: _autosummary
    :template: custom-module-template.rst

docs/source/conf.py

@@ -111,6 +111,13 @@
 # Avoid errors with self-signed certificates
 tls_verify = False
 
+# Avoid warning about api.rst not in TOC
+suppress_warnings = ["toc.not_included", "misc.highlighting_failure"]
+
+nitpick_ignore = [
+    ("py:class", "gaps.config._ConfigType"),
+]
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
@@ -208,6 +215,74 @@
     ),
 ]
 
+
+def _skip_pydantic_methods(name, obj):
+    return name in {
+        "model_dump_json",
+        "model_json_schema",
+        "model_dump",
+        "model_construct",
+        "model_copy",
+        "model_fields",
+        "model_computed_fields",
+        "model_rebuild",
+        "model_parametrized_name",
+        "model_post_init",
+        "model_validate",
+        "model_validate_json",
+        "model_validate_strings",
+        "copy",
+        "construct",
+        "dict",
+        "from_orm",
+        "json",
+        "parse_file",
+        "parse_obj",
+        "parse_raw",
+        "schema",
+        "schema_json",
+        "update_forward_refs",
+        "validate",
+    } and "BaseModel" in str(obj)
+
+
+def _skip_builtin_methods(name, obj):
+    if name in {
+        "clear",
+        "pop",
+        "popitem",
+        "setdefault",
+        "update",
+    } and "MutableMapping" in str(obj):
+        return True
+
+    if name in {"items", "keys", "values"} and "Mapping" in str(obj):
+        return True
+
+    return name in {"copy", "get"} and "UserDict" in str(obj)
+
+
+def _skip_internal_api(name, obj):
+    if (getattr(obj, "__doc__", None) or "").startswith("[NOT PUBLIC API]"):
+        return True
+
+    return name in {"copy", "fromkeys"} and "Status" in str(obj)
+
+
+def _skip_member(app, what, name, obj, skip, options):
+    if (
+        _skip_internal_api(name, obj)
+        or _skip_builtin_methods(name, obj)
+        or _skip_pydantic_methods(name, obj)
+    ):
+        return True
+    return None
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", _skip_member)
+
+
 # -- Extension configuration -------------------------------------------------
 
 autosummary_generate = True  # Turn on sphinx.ext.autosummary

gaps/batch.py

@@ -63,7 +63,7 @@ def __init__(self, config):
 
     @property
     def job_table(self):
-        """pd.DataFrame: Batch job summary table"""
+        """pandas.DataFrame: Batch job summary table"""
         jobs = []
         for job_tag, (arg_comb, file_set, set_tag) in self._sets.items():
             job_info = {k: str(v) for k, v in arg_comb.items()}

gaps/cli/config.py

@@ -567,7 +567,7 @@ def run_with_status_updates(
 
     status_update_args : iterable
         An iterable containing the first three initializer arguments for
-        :class:`StatusUpdates`.
+        :class:`~gaps.status.StatusUpdates`.
     exclude : collection | None
         A collection (list, set, dict, etc.) of keys that should be
         excluded from the job status file that is written before/after

gaps/cli/documentation.py

@@ -389,6 +389,7 @@ class CommandDocumentation:
     """
 
     REQUIRED_TAG = "[REQUIRED]"
+    """Tag to indicate required parameters in generated templates"""
 
     def __init__(self, *functions, skip_params=None, is_split_spatially=False):
         """

gaps/cli/preprocessing.py

@@ -22,7 +22,8 @@ def split_project_points_into_ranges(config):
     ----------
     config : dict
         Run config. This config must have a "project_points" input that
-        can be used to initialize :class:`ProjectPoints`.
+        can be used to initialize
+        :class:`gaps.project_points.ProjectPoints`.
 
     Returns
     -------

gaps/collection.py

@@ -570,7 +570,7 @@ def _check_meta(self, meta):
 
         Parameters
         ----------
-        meta : :class:`pd.DataFrame`
+        meta : pandas.DataFrame
             DataFrame of combined meta from all files in
             `self.h5_files`. Duplicate GIDs are dropped and a warning is
             raised.
@@ -897,7 +897,7 @@ def parse_meta(h5_file):
 
     Returns
     -------
-    meta : :class:`pd.DataFrame`
+    meta : pandas.DataFrame
         Portion of meta data corresponding to sites in `h5_file`.
     """
     with Resource(h5_file) as res:

gaps/config.py

@@ -77,6 +77,7 @@ class JSONHandler(Handler):
     """JSON config file handler"""
 
     FILE_EXTENSION = "json"
+    """Expected file extension for JSON config files"""
 
     @classmethod
     def dump(cls, config, stream):
@@ -98,6 +99,7 @@ class JSON5Handler(Handler):
     """JSON5 config file handler"""
 
     FILE_EXTENSION = "json5"
+    """Expected file extension for JSON5 config files"""
 
     @classmethod
     def dump(cls, config, stream):
@@ -127,6 +129,7 @@ class YAMLHandler(Handler):
     """YAML config file handler"""
 
     FILE_EXTENSION = "yaml", "yml"
+    """Expected file extensions for YAML config files"""
 
     @classmethod
     def dump(cls, config, stream):
@@ -148,6 +151,7 @@ class TOMLHandler(Handler):
     """TOML config file handler"""
 
     FILE_EXTENSION = "toml"
+    """Expected file extension for TOML config files"""
 
     @classmethod
     def dump(cls, config, stream):
@@ -176,6 +180,7 @@ def _new_post_hook(cls, obj, value):
         obj.load = _CONFIG_HANDLER_REGISTRY[value].load
         obj.loads = _CONFIG_HANDLER_REGISTRY[value].loads
         obj.write = _CONFIG_HANDLER_REGISTRY[value].write
+        obj.__doc__ = f"{value} config"
         return obj
 
 
@@ -190,7 +195,7 @@ def _new_post_hook(cls, obj, value):
 
 
 def config_as_str_for_docstring(
-    config, config_type=ConfigType.JSON, num_spaces=12
+    config, config_type=str(ConfigType.JSON), num_spaces=12
 ):
     """Convert a config into a string to be used within a docstring.
 
@@ -202,11 +207,11 @@ def config_as_str_for_docstring(
     config : dict
         Dictionary containing the configuration to be converted into
         docstring format.
-    config_type : :class:`ConfigType`, optional
+    config_type : ConfigType, default="json"
         A :class:`ConfigType` enumeration value specifying what type
-        of config file to generate. By default, :attr:`ConfigType.JSON`.
-    num_spaces : int, optional
-        Number of spaces to add after a newline. By default, `12`.
+        of config file to generate. By default, "json".
+    num_spaces : int, default=12
+        Number of spaces to add after a newline. By default, ``12``.
 
     Returns
     -------

gaps/hpc.py

@@ -29,9 +29,9 @@ class HpcJobManager(ABC):
     """Abstract HPC job manager framework"""
 
     # set a max job name length, will raise error if too long.
-    MAX_NAME_LEN = 100
+    _MAX_NAME_LEN = 100
 
-    SHELL_FILENAME_FMT = "{}.sh"
+    _SHELL_FILENAME_FMT = "{}.sh"
 
     def __init__(self, user=None, queue_dict=None):
         """
@@ -206,7 +206,7 @@ def submit(
         self._setup_submission(name, **kwargs)
 
         out, err = submit(
-            f"{self.COMMANDS.SUBMIT} {self.SHELL_FILENAME_FMT.format(name)}"
+            f"{self.COMMANDS.SUBMIT} {self._SHELL_FILENAME_FMT.format(name)}"
         )
         out = self._teardown_submission(name, out, err, keep_sh=keep_sh)
         return out, err
@@ -222,10 +222,10 @@ def _validate_command_not_none(self, command):
 
     def _validate_name_length(self, name):
         """Validate that the name does not exceed max length"""
-        if len(name) > self.MAX_NAME_LEN:
+        if len(name) > self._MAX_NAME_LEN:
             msg = (
                 f"Cannot submit job with name longer than "
-                f"{self.MAX_NAME_LEN} chars: {name!r}"
+                f"{self._MAX_NAME_LEN} chars: {name!r}"
             )
             raise gapsValueError(msg)
 
@@ -236,12 +236,12 @@ def _setup_submission(self, name, **kwargs):
 
         script = self.make_script_str(name, **kwargs)
 
-        make_sh(self.SHELL_FILENAME_FMT.format(name), script)
+        make_sh(self._SHELL_FILENAME_FMT.format(name), script)
 
     def _teardown_submission(self, name, out, err, keep_sh=False):
         """Remove submission file and mark job as submitted"""
         if not keep_sh:
-            Path(self.SHELL_FILENAME_FMT.format(name)).unlink()
+            Path(self._SHELL_FILENAME_FMT.format(name)).unlink()
 
         if err:
             warn(
@@ -316,11 +316,13 @@ class PBS(HpcJobManager):
     """Subclass for PBS subprocess jobs"""
 
     COLUMN_HEADERS = Q_COLUMNS(NAME="Name", ID="Job id", STATUS="S")
+    """PBS output column header names"""
 
-    # String representing the submitted status for this manager
     Q_SUBMITTED_STATUS = "Q"
+    """String representing the submitted status for this manager"""
 
     COMMANDS = COMMANDS(SUBMIT="qsub", CANCEL="qdel")  # cspell:disable-line
+    """Submission and cancellation command names for this manager"""
 
     def query_queue(self):
         """Run the PBS qstat command and return the raw stdout string.
@@ -431,12 +433,15 @@ class SLURM(HpcJobManager):
 
     # cspell:disable-next-line
     COLUMN_HEADERS = Q_COLUMNS(NAME="NAME", ID="JOBID", STATUS="ST")
+    """SLURM output column names"""
 
     # String representing the submitted status for this manager
     Q_SUBMITTED_STATUS = "PD"
+    """String representing the submitted status for this manager"""
 
     # cspell:disable-next-line
     COMMANDS = COMMANDS(SUBMIT="sbatch", CANCEL="scancel")
+    """Submission and cancellation command names for this manager"""
 
     def query_queue(self):
         """Run the HPC queue command and return the raw stdout string.
@@ -449,7 +454,7 @@ def query_queue(self):
         """
         cmd = (
             f'squeue -u {self._user} --format="%.15i %.30P '
-            f'%.{self.MAX_NAME_LEN}j %.20u %.10t %.15M %.25R %q"'
+            f'%.{self._MAX_NAME_LEN}j %.20u %.10t %.15M %.25R %q"'
         )
         stdout, _ = submit(cmd)
         return _skip_q_rows(stdout)

gaps/pipeline.py

@@ -24,6 +24,7 @@ class PipelineStep:
     """A Pipeline Config step"""
 
     COMMAND_KEY = "command"
+    """Key in pipeline step dictionary that specifies the command"""
     _KEYS_PER_STEP = 2
 
     def __init__(self, step_dict):
@@ -61,6 +62,7 @@ class Pipeline:
     """gaps pipeline execution framework"""
 
     COMMANDS = {}
+    """Pipeline command registry"""
 
     def __init__(self, pipeline, monitor=True):
         """