Change to sphinx-click and clean up heading underlining to correct length.

Author: Eli

docsrc/commands.rst

@@ -18,7 +18,7 @@ Use the `dms` grouped CLI (or call commands directly by script name).
    dms download_ncro --help
 
 Command Help Shortcuts
------------------------
+----------------------
 
 .. code-block:: bash
 
@@ -54,7 +54,7 @@ Command Help Shortcuts
    rationalize_time_partitions --help
 
 Workflow A: Repository Build Pipeline (Download → Reformat → Auto Screen)
------------------------------------------------------------------------
+-------------------------------------------------------------------------
 
 Stage 1: Download into raw/staging
 
@@ -124,7 +124,7 @@ Workflow B: Dropbox Ingest (separate workflow)
    dropbox --input dms_datastore/config_data/dropbox_spec.yaml
 
 Workflow C: Staging → Repo update and utilities
-------------------------------------------------
+-----------------------------------------------
 
 .. code-block:: bash
 
@@ -134,4 +134,4 @@ Workflow C: Staging → Repo update and utilities
 Additional Utilities
 --------------------
 
-See the documentation for details and examples for `station_info`, `merge_files`, `coarsen`, and other utilities.
+See the documentation for details and examples for `station_info`, `merge_files`, `coarsen`, and other utilities.

docsrc/concepts.rst

@@ -155,7 +155,7 @@ Units and Standardization
 
 
 Known Challenges and Exceptions
-================================
+===============================
 
 **WDL Station IDs**
    WDL station IDs may not match the canonical ``station_id`` due to appended ``"00"``
@@ -170,4 +170,3 @@ Known Challenges and Exceptions
    USGS may have multiple instruments measuring the same variable for one station ID
    due to different programs or sublocations. The ``raw/`` directory can store dual
    versions for QA/QC, though the processed set should ideally be unified.
-

docsrc/conf.py

@@ -16,8 +16,35 @@
 
 
 # -- Project information -----------------------------------------------------
-import dms_datastore
+import sys
 import os
+from unittest.mock import MagicMock
+
+# Mock heavy/unavailable dependencies before importing dms_datastore,
+# so conf.py works in the CI docs environment without the full conda env.
+_MOCK_MODULES = [
+    "vtools", "vtools.data", "vtools.data.indexing", "vtools.data.vtime",
+    "vtools.data.timeseries", "vtools.data.gap", "vtools.data.duplicate_index",
+    "vtools.functions", "vtools.functions.merge", "vtools.functions.filter",
+    "vtools.functions.coarsen", "vtools.functions.error_detect",
+    "vtools.functions.unit_conversions",
+    "schimpy", "schimpy.station", "schimpy.unit_conversions",
+    "tabula",
+    "geopandas",
+    "shapely", "shapely.geometry",
+    "diskcache",
+    "seaborn",
+    "dask", "dask.dataframe",
+    "paramiko",
+    "boto3",
+    "cfgrib",
+    "eccodes",
+    "numba",
+]
+for _mod in _MOCK_MODULES:
+    sys.modules.setdefault(_mod, MagicMock())
+
+import dms_datastore
 
 project = 'dms_datastore'
 copyright = '2022, Eli Ateljevich, CA DWR'
@@ -43,19 +70,23 @@
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-extensions = [ 'sphinx_rtd_theme', 'nbsphinx',
-          'sphinxcontrib.mermaid',
-          'sphinx.ext.mathjax',
-          'sphinx.ext.autodoc', 
-          'sphinx.ext.viewcode',
-          'matplotlib.sphinxext.mathmpl',
-          'matplotlib.sphinxext.plot_directive',
-          'sphinx.ext.intersphinx',
-          'sphinx.ext.autodoc',
-          #'sphinx_argparse_cli',
-          'sphinxarg.ext',
-          'sphinx.ext.doctest',
-          'numpydoc']
+extensions = [
+    'sphinx_rtd_theme',
+    'nbsphinx',
+    'sphinxcontrib.mermaid',
+    'sphinx.ext.mathjax',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'matplotlib.sphinxext.mathmpl',
+    'matplotlib.sphinxext.plot_directive',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autodoc',
+    #'sphinx_argparse_cli',
+    'sphinxarg.ext',
+    'sphinx_click',
+    'sphinx.ext.doctest',
+    'numpydoc',
+]
 
 autodoc_member_order = 'alphabetical'
 

docsrc/download_data.rst

@@ -14,31 +14,25 @@ Station Lists
 
 
 Specific Command Line Interfaces
-=================================
+================================
 
 CDEC
-^^^^^^
-.. argparse::
-    :module: dms_datastore.download_cdec
-    :func: create_arg_parser
+^^^^
+.. click:: dms_datastore.download_cdec:download_cdec_cli
     :prog: download_cdec
 
 
 
 USGS (NWIS)
-^^^^^^^^^^^^^
+^^^^^^^^^^^
 
-.. argparse::
-    :module: dms_datastore.download_nwis
-    :func: create_arg_parser
+.. click:: dms_datastore.download_nwis:download_nwis_cli
     :prog: download_nwis
 
 NOAA
 ^^^^
 
-.. argparse::
-    :module: dms_datastore.download_noaa
-    :func: create_arg_parser
+.. click:: dms_datastore.download_noaa:download_noaa_cli
     :prog: download_noaa
 
 DWR-NCRO
@@ -55,17 +49,12 @@ so its interface is simpler, less flexible and different from the others.
 #    :module: dms_datastore.download_ncro
 #    :func: create_arg_parser
 #    :prog: download_ncro.py
-
+    
+.. click:: dms_datastore.download_des:download_des_cli
+    :prog: download_des
 DWR-DES (DISE)
 ^^^^^^^^^^^^^^
 
 DWR Division of Environmental Services has been renamed but the name has not yet been updated here. 
 These web services are internal to DWR. External users can get reformatted/screened data from our group or request data 
 from DWR liasons who are identified on CDEC on a per-station basis.
-
-.. argparse::
-    :module: dms_datastore.download_des
-    :func: create_arg_parser
-    :prog: download_des
-
-

docsrc/dropbox.rst

@@ -22,7 +22,7 @@ Key Components
    metadata inference rules.
 
 How it works
------------
+------------
 
 The processing follows these steps:
 

docsrc/read_data_meta.rst

@@ -87,7 +87,7 @@ Additional methods from ``vtools3``
 
 
 Reading Data with ``read_ts_repo``
-===================================
+==================================
 
 :func:`~dms_datastore.read_multi.read_ts_repo` is the primary way to access data
 from the datastore. It handles file path construction, source prioritization,
@@ -150,7 +150,7 @@ Function parameters
 
 
 Example: retrieval and visualization
--------------------------------------
+------------------------------------
 
 .. code-block:: python
 
@@ -176,7 +176,7 @@ Example: retrieval and visualization
 
 
 Caching repeated reads
------------------------
+----------------------
 
 For repeated access to the same data the datastore provides the
 ``@cache_dataframe`` decorator:
@@ -199,4 +199,4 @@ For repeated access to the same data the datastore provides the
    # Subsequent calls use cached data
    daily_flow = get_filtered_flow(station="sjj", variable="flow")
 
-See also the :doc:`Local Caching notebook <notebooks/cache>` for a hands-on walkthrough.
+See also the :doc:`Local Caching notebook <notebooks/cache>` for a hands-on walkthrough.

docsrc/repository.rst

@@ -1,8 +1,8 @@
 
 
-###########################
+########################
 Time Series Repositories
-###########################
+########################
 
 This page describes the design of the repository system for developers and advanced
 users who need to build inventory tools, implement downloaders, or integrate with
@@ -25,7 +25,7 @@ These form a strict, deterministic pipeline::
 
 
 Repository Configuration
-=========================
+========================
 
 A repo configuration defines how a directory of files is interpreted as structured data.
 
@@ -70,7 +70,7 @@ Key terminology
 
 
 Source Priority Configuration
-------------------------------
+-----------------------------
 
 The ``source_priority`` block in ``dstore_config.yaml`` specifies preferred data
 sources per agency-managed station group:
@@ -93,7 +93,7 @@ For example, EBMUD station data is resolved by preferring USGS, then EBMUD, then
 
 
 Filename Templates and Interpretation
-======================================
+=====================================
 
 Filename templates define the bidirectional mapping between metadata and filenames.
 
@@ -120,7 +120,7 @@ Design rules:
 
 
 Registry (station_dbase.csv)
-=============================
+============================
 
 The registry provides authoritative metadata that enriches filename-derived fields.
 
@@ -138,7 +138,7 @@ Inventory System
 Inventory converts repository files into structured summaries.
 
 File inventory (``repo_file_inventory``)
------------------------------------------
+----------------------------------------
 
 Groups by ``file_pattern``. Represents:
 
@@ -147,7 +147,7 @@ Groups by ``file_pattern``. Represents:
 * Provider-specific datasets
 
 Data inventory (``repo_data_inventory``)
------------------------------------------
+----------------------------------------
 
 Groups by ``series_id``. Represents:
 
@@ -167,7 +167,7 @@ A ``series_id`` is constructed from metadata::
 
 
 Populating the Repository
-==========================
+=========================
 
 The :doc:`commands` page documents the full CLI workflow. A summary::
 
@@ -225,7 +225,7 @@ Guarantees: stable formatting, idempotent round-trip, canonical YAML header.
 
 
 End-to-End Flow
-================
+===============
 
 Read path::
 
@@ -241,7 +241,7 @@ Write path::
 
 
 Design Principles
-==================
+=================
 
 Fail fast
    Bad filenames → error. Bad config → error. No implicit recovery.
@@ -265,7 +265,7 @@ Separation of concerns
 
 
 Architectural Evolution Notes
-==============================
+=============================
 
 The repository system was refactored from an implicit agency-based model to a fully
 config-driven provider model. Key terminology changes:
@@ -284,5 +284,4 @@ Configs **must** define ``site_key``, ``provider_key``, and
 ``provider_resolution_mode``. Misconfigured repos fail immediately — there is
 no fallback behavior.
 
-The legacy ``parse.style = legacy`` option remains for backward compatibility.
-
+The legacy ``parse.style = legacy`` option remains for backward compatibility.

docsrc/requirements.txt

@@ -13,3 +13,5 @@ pandoc
 matplotlib # needed for matplotlib.sphinxext.mathmply
 ipython    # neededd for IPython.sphinxext.ipython_directive
 pip
+sphinx-click
+click

docsrc/station_info.rst

@@ -14,7 +14,7 @@ See :doc:`commands` for the full CLI reference.
 
 
 Configuration System
-=====================
+====================
 
 The datastore uses YAML files and Python modules to manage station metadata,
 variable mappings, and screening configurations.
@@ -76,7 +76,7 @@ All functions cache their results to avoid repeated filesystem reads.
 
 
 Screen Configuration
----------------------
+--------------------
 
 The screening configuration YAML (referenced by ``screen_config`` in
 ``dstore_config.yaml``) drives :mod:`~dms_datastore.auto_screen` and contains
@@ -85,4 +85,4 @@ rule sets for:
 * **Bounds checking** — acceptable min/max values per variable
 * **Spike detection** — parameters for flagging data spikes
 * **Repetition checking** — rules for flagging suspicious repeated values
-* **Custom screening functions** — advanced algorithms for specific data types
+* **Custom screening functions** — advanced algorithms for specific data types