Merge pull request #229 from lsst-sqre/tickets/DM-45803

DM-45803: Remove pipelines.lsst.io-related extensions and configuration

Author: jonathansick

.github/workflows/ci-cron.yaml

@@ -4,6 +4,9 @@
 
 name: Periodic CI
 
+env:
+  PYTHON_VERSION: "3.12"
+
 "on":
   schedule:
     - cron: "0 12 * * 1"
@@ -19,6 +22,7 @@ jobs:
           - "3.12"
         sphinx-version:
           - "7"
+          - "8"
           - "dev"
 
     steps:
@@ -64,7 +68,7 @@ jobs:
       - name: Build docs in tox
         uses: lsst-sqre/run-tox@v1
         with:
-          python-version: "3.12"
+          python-version: ${{ env.PYTHON_VERSION }}
           tox-envs: "docs,docs-lint"
           use-cache: false
 
@@ -94,5 +98,5 @@ jobs:
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: "3.12"
+          python-version: ${{ env.PYTHON_VERSION }}
           upload: false

.github/workflows/ci.yaml

@@ -1,5 +1,8 @@
 name: CI
 
+env:
+  PYTHON_VERSION: '3.12' # Default Python version
+
 'on':
   push:
     branches-ignore:
@@ -39,6 +42,7 @@ jobs:
           - '3.12'
         sphinx-version:
           - '7'
+          - '8'
 
     steps:
       - uses: actions/checkout@v4
@@ -76,7 +80,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # full history for setuptools_scm
 
@@ -86,7 +90,7 @@ jobs:
       - name: Run tox
         uses: lsst-sqre/run-tox@v1
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}
           tox-envs: 'docs,docs-lint'
 
       # Only attempt documentation uploads for tagged releases and pull
@@ -115,7 +119,7 @@ jobs:
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: "3.12"
+          python-version: ${{ env.PYTHON_VERSION }}
           upload: "false"
 
   pypi-publish:
@@ -147,4 +151,4 @@ jobs:
       - name: Build and publish
         uses: lsst-sqre/build-and-publish-to-pypi@v2
         with:
-          python-version: '3.12'
+          python-version: ${{ env.PYTHON_VERSION }}

.github/workflows/dependencies.yaml

@@ -14,29 +14,19 @@ repos:
       - id: rst-linter
         files: (README\.rst)|(CHANGELOG\.rst)
 
-  - repo: https://github.com/PyCQA/isort/
-    rev: 5.13.2
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1
     hooks:
-      - id: isort
-        additional_dependencies:
-          - toml
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
 
-  - repo: https://github.com/psf/black
-    rev: 24.4.2
-    hooks:
-      - id: black
-
-  - repo: https://github.com/asottile/blacken-docs
-    rev: 1.16.0
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.18.0
     hooks:
       - id: blacken-docs
-        additional_dependencies: [black==22.12.0]
-        args: [-l, '79', -t, py38]
-
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.0.0
-    hooks:
-      - id: flake8
+        additional_dependencies: [black==24.4.2]
+        args: [-l, '79', -t, py312]
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: v4.0.0-alpha.8

.pre-commit-config.yaml

@@ -1,6 +1,4 @@
 {
   "[python]": {
-    "editor.defaultFormatter": "ms-python.black-formatter"
-  },
-  "python.formatting.provider": "none"
+  }
 }

.vscode/settings.json

@@ -0,0 +1,33 @@
+### Backwards-incompatible changes
+
+- All Science Pipelines-related tooling and Sphinx extensions have been removed from Documenteer, and can now be found in a new Science Pipelines package called `sphinxutils` (https://github.com/lsst-dm/sphinxutils). Specific removals include:
+
+  - `documenteer.stackdocs`
+  - Configurations `documenteer.conf.pipelines` and `documenteer.conf.pipelinespkg`
+  - CLI commands `stack-docs` and `package-docs`
+  - Sphinx extensions:
+    - `documenteer.ext.lssttasks`
+    - `documenteer.ext.packagetoctree`
+    - `documenteer.ext.autocppapi`
+    - `documenteer.ext.autodocreset`
+
+### New features
+
+- User guide configuration improvements:
+
+  - New custom automodapi templates for Pydantic BaseModels and exceptions. The exception template ensures that inherited members of exceptions are documented. The Pydantic BaseModel template ensures that inherited members from the `BaseModel` class itself are _not_ documented. These templates were originally developed as part of [Gafaelfawr](https://github.com/lsst-sqre/gafaelfawr). Now users of the user guide configuration benefit from these templates without any additional configuration.
+
+  - The `[guide]` installation extra and `documenteer.conf.guide` configuration now include `autodoc_pydantic` for improved documentation of Pydantic models in Python API references.
+
+  - The `documenteer.conf.guide` configuration now ignores common Sphinx warnings that are common when including references to projects that don't use Sphinx/Intersphinx for this documentation, including Pydantic and FastAPI.
+
+- The entire `documenteer` code base is now type annotated.
+
+### Bug fixes
+
+-
+
+### Other changes
+
+- The code base is now linted and formatted with ruff.
+- Start testing against Sphinx 8.

changelog.d/20240819_152413_jsick_DM_45803.md

@@ -1,8 +1,7 @@
 # Makefile for Sphinx documentation
 
 # You can set these variables from the command line.
-# SPHINXOPTS    = -n -W
-SPHINXOPTS    = -n
+SPHINXOPTS    = -n -W
 SPHINXBUILD   = sphinx-build
 BUILDDIR      = _build
 

docs/Makefile

@@ -27,7 +27,6 @@
 .. _TOML: https://toml.io/en/
 .. _`SQR-006`: https://sqr-006.lsst.io
 .. _`lsstDoxygen`: https://github.com/lsst/lsstDoxygen
-.. _`package-docs`: https://documenteer.lsst.io/pipelines/package-docs-cli.html
 .. _`pex_config`: https://github.com/lsst/pex_config
 .. _`pipe_base`: https://github.com/lsst/pipe_base
 .. _`pipe_supertask`: https://github.com/lsst/pipe_supertask
@@ -70,10 +69,6 @@
 
 .. |documenteer.toml| replace:: :doc:`documenteer.toml </guides/toml-reference>`
 .. |documenteer.conf.guide| replace:: :doc:`documenteer.conf.guide </guides/configuration-preset>`
-.. |package-docs| replace:: :doc:`package-docs </guides/pipelines/package-docs-cli>`
-.. |stack-docs| replace:: :doc:`stack-docs </guides/pipelines/stack-docs-cli>`
-.. |stack-docs-build| replace:: :doc:`stack-docs build </guides/pipelines/stack-docs-cli>`
-.. |stack-docs-clean| replace:: :doc:`stack-docs clean </guides/pipelines/stack-docs-cli>`
 
 .. links to sphinx directives
 

docs/_rst_epilog.rst

@@ -2,10 +2,6 @@
 documenteer.ext
 ###############
 
-.. automodapi:: documenteer.ext.autocppapi
-
-.. automodapi:: documenteer.ext.autodocreset
-
 .. automodapi:: documenteer.ext.openapi
 
 .. automodapi:: documenteer.ext.bibtex
@@ -20,6 +16,3 @@ documenteer.ext
 
 .. automodapi:: documenteer.ext.mockcoderefs
    :no-inheritance-diagram:
-
-.. automodapi:: documenteer.ext.packagetoctree
-   :no-inheritance-diagram:

docs/dev/api/documenteer.ext.rst

@@ -8,5 +8,3 @@ Python API
    documenteer.conf
    documenteer.ext
    documenteer.requestsutils
-   documenteer.sphinxrunner
-   documenteer.stackdocs

docs/dev/api/documenteer.sphinxrunner.rst

@@ -11,6 +11,7 @@ package = "documenteer"
 extensions = [
   "sphinx_click.ext",
   "sphinxcontrib.autoprogram",
+  "sphinxcontrib.autodoc_pydantic"
 ]
 disable_primary_sidebars = ["index", "changelog"]
 rst_epilog_file = "_rst_epilog.rst"
@@ -25,7 +26,8 @@ nitpick_ignore_regex = [
 ]
 python_api_dir = "dev/api/contents"
 exclude = [
-  "technotes/_templates/*"
+  "technotes/_templates/*",
+  "_templates/**"
 ]
 
 [sphinx.theme]
@@ -46,10 +48,10 @@ ignore = [
 ]
 
 [sphinx.redirects]
-"pipelines/build-overview.rst" = "guides/pipelines/build-overview.rst"
-"pipelines/configuration.rst" = "guides/pipelines/configuration.rst"
-"pipelines/cpp-api-linking.rst" = "guides/pipelines/cpp-api-linking.rst"
-"pipelines/index.rst" = "guides/pipelines/index.rst"
-"pipelines/install.rst" = "guides/pipelines/install.rst"
-"pipelines/package-docs-cli.rst" = "guides/pipelines/package-docs-cli.rst"
-"pipelines/stack-docs-cli.rst" = "guides/pipelines/stack-docs-cli.rst"
+"pipelines/build-overview.rst" = "guides/index.rst"
+"pipelines/configuration.rst" = "guides/index.rst"
+"pipelines/cpp-api-linking.rst" = "guides/index.rst"
+"pipelines/index.rst" = "guides/index.rst"
+"pipelines/install.rst" = "guides/index.rst"
+"pipelines/package-docs-cli.rst" = "guides/index.rst"
+"pipelines/stack-docs-cli.rst" = "guides/index.rst"

docs/dev/api/documenteer.stackdocs.rst

@@ -47,14 +47,6 @@ Documenteer provides a configuration profile for creating branded user guides wi
    markdown-primer
    including-notebooks
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Science Pipelines
-   :name: toc-guides-pipelines
-   :titlesonly:
-
-   pipelines/index
-
 .. toctree::
    :maxdepth: 2
    :caption: Reference

docs/dev/api/index.rst

@@ -23,7 +23,7 @@ These paths are relative to the documentation project's root directory (where :f
 The table accepts an arbitrary number of redirects:
 
 .. code-block:: toml
-   :captin: documenteer.toml
+   :caption: documenteer.toml
 
    [sphinx.redirects]
    "old-page.rst" = "some-dir/new-page.rst"