Documentation Tooling Updates (#1718)

* remove circleci documentation workflow

* move makefile logic to make.py and update sphinx config

* create new documentation workflow

* add sphinx-lint dependency, job, and pre-commit hook

* add final newline, trailing whitespace, and yaml+toml syntax checks to pre-commit workflow

* resolve unsupported theme option 'display_version' given

* update source_suffix from list to dictionary

* add sphinx workflow cache

* exclude sphinx outputs from git

* fix copying of index redirect

* indentation for index.html

* use furo theme

* add furo to requirements-dev

* keep old build files < 5.0.0 between runs

* Update dependency-review.yml to whitelist url and remove GHSA allowance

Removed specific GHSA allowance from dependency review action.

* add pydocstyle ruff rules

* reduce_rows raw docstring

* run pre-commit

* Delete .circleci directory

* add make.py and conf.py to sphinx cache key

---------

Co-authored-by: Shauna Gordon-McKeon <shaunagm@gmail.com>

Author: bmos

.circleci/config.yml

@@ -0,0 +1,87 @@
+name: Documentation CI/CD
+
+on:
+  workflow_dispatch:
+  pull_request:
+  push:
+    branches:
+      - main
+      - major-release
+
+permissions: read-all
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            files.pythonhosted.org:443
+            github.com:443
+            pypi.org:443
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          # If it's a push (main or major-release) or workflow_dispatch, get full history.
+          fetch-depth: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 0 || 1 }}
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: '3.13'
+          cache: pip
+
+      - uses: install-pinned/uv@259f91feb61b6e94766d7a1dbcd5f17335370e64
+
+      - run: |
+          uv pip install --system -e .[all]
+          uv pip install --system -r requirements-dev.txt
+
+      - name: configure git
+        run: |
+          git config user.name "github-actions"
+          git config user.email "github-actions@github.com"
+
+      - uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306
+        with:
+          path: docs/html
+          key: >-
+            sphinx
+            -${{ hashFiles('pyproject.toml') }}
+            -${{ hashFiles('setup.py') }}
+            -${{ hashFiles('requirements-dev.txt') }}
+            -${{ hashFiles('docs/make.py') }}
+            -${{ hashFiles('docs/conf.py') }}
+
+      - run: make build_docs
+        working-directory: docs
+
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b
+        with:
+          path: docs/html/
+
+  deploy:
+    needs: build
+    # Only run this job if triggered by updating the main branch
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
+        with:
+          disable-sudo: true
+          egress-policy: audit
+
+      - uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e

.github/workflows/documentation.yml

@@ -21,6 +21,7 @@ env:
   ENDPOINT_WHITELIST: >-
     pypi.org:443
     github.com:443
+    releases.astral.sh
     files.pythonhosted.org:443
     *.github.com:443
     *.githubusercontent.com:443
@@ -54,13 +55,7 @@ jobs:
         with:
           disable-sudo: true
           egress-policy: block
-          allowed-endpoints: >
-            api.github.com:443
-            auth.docker.io:443
-            files.pythonhosted.org:443
-            github.com:443
-            pypi.org:443
-            raw.githubusercontent.com:443
+          allowed-endpoints: auth.docker.io:443 ${{ env.ENDPOINT_WHITELIST}}
 
       - run: |
           echo "\
@@ -332,13 +327,44 @@ jobs:
           name: python-coverage-comment-action
           path: python-coverage-comment-action.txt
 
+  sphinx-lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
+        with:
+          disable-sudo: true
+          egress-policy: block
+          allowed-endpoints: >
+            files.pythonhosted.org:443
+            github.com:443
+            pypi.org:443
+
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version: '3.13'
+          cache: pip
+
+      - uses: install-pinned/uv@259f91feb61b6e94766d7a1dbcd5f17335370e64
+
+      - run: |
+          uv pip install --system -e .[all]
+          uv pip install --system -r requirements-dev.txt
+
+      - run: sphinx-lint docs
+
+      - run: sphinx-lint parsons
+
   pre-commit:
     runs-on: ubuntu-latest
 
     needs:
+      - bandit
       - ruff-format
       - ruff-check
-      - bandit
+      - sphinx-lint
 
     permissions:
       contents: write

.github/workflows/python-checks.yml

@@ -1,13 +1,27 @@
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.13.0
     hooks:
       - id: ruff-check
-        args: ['--fix']      
+        args: ['--fix']
       - id: ruff-format
+
   - repo: https://github.com/PyCQA/bandit
     rev: 1.8.6
     hooks:
       - id: bandit
         args: ['--confidence-level', 'medium', '--severity-level', 'medium', '--exclude', '**/vendor/*']
         files: '^parsons'
+
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: v1.0.2
+    hooks:
+      - id: sphinx-lint

.pre-commit-config.yaml

@@ -1,26 +1,16 @@
-# Minimal makefile for Sphinx documentation
-#
+PYTHON     := python3
+SCRIPT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+SCRIPT     := $(SCRIPT_DIR)make.py
 
-# You can set these variables from the command line.
-SPHINXOPTS    = -a
-SPHINXBUILD   = sphinx-build
-SPHINXPROJ    = Parsons
-SOURCEDIR     = .
-BUILDDIR      = .
+.PHONY: % check_python
 
-# Put it first so that "make" without argument is like "make help".
-help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+Makefile: ;
 
-deploy_docs:
-	git branch latest
-	git branch stable $$(git tag -l --sort=creatordate | tail -1)
-	sphinx-multiversion . html
-	cp ./index-redirect.html html/index.html
+%: check_python
+	@$(PYTHON) "$(SCRIPT)" $@ $(filter-out $@,$(MAKECMDGOALS))
 
-.PHONY: help Makefile
+check_python:
+	@$(PYTHON) --version > /dev/null 2>&1 || (echo "Error: Python not found."; exit 1)
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+$(filter-out $(firstword $(MAKECMDGOALS)),$(MAKECMDGOALS)):
+	@:

docs/Makefile

@@ -36,4 +36,3 @@ API
 .. autoclass:: parsons.yourconnector.yourconnector.YourConnector
    :inherited-members:
    :members:
-