Switch docs action to use sphinxutils.

Author: MichelleGower

.github/workflows/build_docs.yaml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: '3.11'
+          python-version: '3.13'
           cache: "pip"
           cache-dependency-path: "setup.cfg"
 
@@ -36,7 +36,7 @@ jobs:
         run: uv pip install --system --no-deps -v .
 
       - name: Install documenteer
-        run: uv pip install --system 'documenteer[pipelines]==0.8.2' sphinx-automodapi==0.19 sphinx-prompt==1.6.0
+        run: uv pip install --system -r doc/requirements.txt
 
       - name: Build documentation
         working-directory: ./doc

.gitignore

@@ -73,6 +73,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+doc/api
 
 # PyBuilder
 target/

doc/changes/DM-54006.misc.rst

@@ -1 +1 @@
-Bumped minimum Python version to 3.12.  Dropped ``black`` and ``isort`` sections from ``pyproject.toml``.
+Bumped minimum Python version to 3.12.  Dropped ``black`` and ``isort`` sections from ``pyproject.toml``.  Switched docs action to use ``sphinxutils``.

doc/conf.py

@@ -3,22 +3,8 @@
 This configuration only affects single-package Sphinx documentation builds.
 """
 
-from documenteer.conf.pipelinespkg import *  # noqa: F403, import *
+# ruff: noqa: F403, F405
 
-project = "ctrl_bps"
-html_theme_options["logotext"] = project  # noqa: F405, unknown name
-html_title = project
-html_short_title = project
-doxylink = {}
-exclude_patterns = ["changes/*"]
+from documenteer.conf.guide import *
 
-# Try to pull in links for butler and pipe_base.
-intersphinx_mapping["lsst"] = ("https://pipelines.lsst.io/v/daily/", None)  # noqa
-intersphinx_mapping["networkx"] = ("https://networkx.org/documentation/stable/", None)  # noqa: F405
-
-# As a temporary hack until we move to documenteer 2 delete scipy
-# (since it no longer works)
-try:
-    del intersphinx_mapping["scipy"]  # noqa: F405
-except KeyError:
-    pass
+exclude_patterns.append("changes/*")

doc/documenteer.toml

@@ -0,0 +1,20 @@
+[project]
+title = "lsst-ctrl-bps"
+
+[project.python]
+package = "lsst-ctrl-bps"
+
+[build]
+clean = true
+
+[sphinx]
+extensions = [
+    "sphinx_click"
+]
+
+[sphinx.intersphinx.projects]
+astropy = "https://docs.astropy.org/en/stable"
+python = "https://docs.python.org/3"
+lsst = "https://pipelines.lsst.io/v/daily/"
+click = "https://click.palletsprojects.com/en/stable"
+networkx = "https://networkx.org/documentation/stable/"

doc/lsst.ctrl.bps/quickstart.rst

@@ -1,3 +1,6 @@
+User Guide
+==========
+
 Overview
 --------
 

doc/requirements.txt

@@ -0,0 +1,3 @@
+documenteer[guide] > 2.0, <3.0
+lsst-sphinxutils @ git+https://github.com/lsst/sphinxutils@main
+sphinx-click

pyproject.toml

@@ -37,8 +37,9 @@ dynamic = ["version"]
 
 [project.urls]
 "Homepage" = "https://github.com/lsst/ctrl_bps"
-[project.optional-dependencies]
+"Source" = "https://github.com/lsst/ctrl_bps"
 
+[project.optional-dependencies]
 test = [
     "pytest >= 3.2",
     "pytest-openfiles >= 0.5.0"
@@ -190,6 +191,7 @@ checks = [
     "RT01",  # Unfortunately our @property trigger this.
     "RT02",  # Does not want named return value. DM style says we do.
     "SS05",  # pydocstyle is better at finding infinitive verb.
+    "RT03",  # Temporarily disable for sphinx empty returns.
 ]
 exclude = [
     '^test_.*',  # Do not test docstrings in test code.

python/lsst/ctrl/bps/bps_config.py

@@ -197,7 +197,7 @@ def get(self, key, default=""):
         ----------
         key : `str`
             Key to look for in config.
-        default : Any, optional
+        default : `~typing.Any`, optional
             Default value to return if the key is not in the config.
 
         Returns

python/lsst/ctrl/bps/generic_workflow.py

@@ -490,7 +490,7 @@ def add_node(self, node_for_adding: GenericWorkflowNode, **attr: Any) -> None:
         ----------
         node_for_adding : `lsst.ctrl.bps.GenericWorkflowJob`
             Job to be added to generic workflow.
-        **attr
+        **attr : `~typing.Any`
             Needed to match original networkx function, but not used.
         """
         self.add_job(node_for_adding)
@@ -524,7 +524,7 @@ def add_edges_from(self, ebunch_to_add: Iterable[tuple[str, str]], **attr: Any)
         ebunch_to_add : Iterable [`tuple` [`str`, `str`]]
             Iterable of job name pairs between which a dependency should be
             saved.
-        **attr : keyword arguments, optional
+        **attr : `~typing.Any`
             Data can be assigned using keyword arguments (not currently used).
         """
         for edge_to_add in ebunch_to_add:
@@ -539,7 +539,7 @@ def add_edge(self, u_of_edge: str, v_of_edge: str, **attr: Any) -> None:
             Name of parent job.
         v_of_edge : `str`
             Name of child job.
-        **attr : keyword arguments, optional
+        **attr
             Attributes to save with edge.
         """
         if u_of_edge not in self: