Skip to content

Commit b0a508b

Browse files
bmosshaunagm
bmos
and
shaunagm
committed
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>
2 parents e8ae273 + 407e61a commit b0a508b

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+409
-476
lines changed

‎.circleci/config.yml‎

Lines changed: 0 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,137 +0,0 @@
1-
version: 2.1
2-
3-
workflows:
4-
version: 2
5-
docs-build:
6-
jobs:
7-
- docs-build
8-
- docs-build-deploy:
9-
requires:
10-
- docs-build
11-
12-
jobs:
13-
docs-build:
14-
docker:
15-
- image: cimg/python:3.13
16-
17-
steps:
18-
- checkout
19-
20-
- restore_cache:
21-
keys:
22-
- v2-dependencies-python3.13-{{ checksum "setup.py" }}-{{ checksum "requirements-dev.txt" }}
23-
# fallback to using the latest cache if no exact match is found
24-
- v2-dependencies-python3.13-
25-
26-
- run:
27-
name: Install dependencies
28-
command: |
29-
uv venv --allow-existing
30-
source .venv/bin/activate
31-
32-
uv pip install -r requirements-dev.txt
33-
uv pip install -e .[all]
34-
35-
- save_cache:
36-
paths:
37-
- ./venv
38-
key: v2-dependencies-python3.13-{{ checksum "setup.py" }}-{{ checksum "requirements-dev.txt" }}
39-
40-
- run:
41-
name: Build docs
42-
command: |
43-
source .venv/bin/activate
44-
45-
cd docs/
46-
make deploy_docs
47-
48-
- store_artifacts:
49-
path: docs/html
50-
51-
- persist_to_workspace:
52-
root: .
53-
paths:
54-
- docs/html
55-
56-
docs-build-deploy:
57-
docker:
58-
- image: cimg/node:current
59-
60-
steps:
61-
- checkout
62-
63-
- attach_workspace:
64-
at: .
65-
66-
- run:
67-
name: Validate build artifacts
68-
command: |
69-
if [ ! -f docs/html/index.html ]; then
70-
echo "Error: docs/html/index.html not found! Build might have failed."
71-
exit 1
72-
fi
73-
74-
- run:
75-
name: Get Latest gh-pages Version
76-
command: |
77-
npm view gh-pages version > gh_pages_version.txt
78-
cat gh_pages_version.txt
79-
80-
- run:
81-
name: Setup NPM Path
82-
command: |
83-
npm set prefix=/home/circleci/npm
84-
echo 'export PATH=/home/circleci/npm/bin:$PATH' >> $BASH_ENV
85-
86-
- run:
87-
name: Setup git
88-
command: |
89-
git config --global user.email "ci-build@movementcooperative.org"
90-
git config --global user.name "ci-build"
91-
git config --global init.defaultBranch main
92-
93-
- restore_cache:
94-
keys:
95-
- v1-gh-pages-{{ checksum "gh_pages_version.txt" }}-{{ arch }}
96-
97-
- run:
98-
name: Install gh-pages
99-
command: |
100-
GH_VERSION=$(cat gh_pages_version.txt)
101-
if [ ! -f /home/circleci/npm/bin/gh-pages ]; then
102-
echo "Installing gh-pages version $GH_VERSION..."
103-
npm install -g --silent gh-pages@$GH_VERSION
104-
fi
105-
106-
- save_cache:
107-
key: v1-gh-pages-{{ checksum "gh_pages_version.txt" }}-{{ arch }}
108-
paths:
109-
- /home/circleci/npm
110-
111-
- add_ssh_keys:
112-
# This SSH key is "CircleCI Docs" in https://github.com/move-coop/parsons/settings/keys
113-
# We need write access to the Parsons repo, so we can push the "gh-pages" branch.
114-
fingerprints:
115-
- '9a:ec:4d:2b:c3:45:b2:f5:55:ca:0b:2b:36:e2:7f:df'
116-
117-
- run:
118-
name: Deploy docs
119-
environment:
120-
CACHE_DIR: /home/circleci/gh-pages-cache
121-
command: |
122-
OPTIONS=(
123-
"--dist" "docs/html"
124-
"--message" "[skip ci] Updates"
125-
"--dotfiles"
126-
"--nojekyll"
127-
)
128-
if [ "$CIRCLE_BRANCH" != "main" ]; then
129-
echo "Verifying gh-pages execution without publishing."
130-
FAKE_REMOTE="/tmp/fake-remote"
131-
mkdir -p "$FAKE_REMOTE"
132-
git init --bare "$FAKE_REMOTE"
133-
gh-pages "${OPTIONS[@]}" --repo "$FAKE_REMOTE"
134-
else
135-
echo "Publishing with gh-pages."
136-
gh-pages "${OPTIONS[@]}"
137-
fi

‎.github/workflows/documentation.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: Documentation CI/CD
2+
3+
on:
4+
workflow_dispatch:
5+
pull_request:
6+
push:
7+
branches:
8+
- main
9+
- major-release
10+
11+
permissions: read-all
12+
13+
jobs:
14+
build:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
19+
with:
20+
disable-sudo: true
21+
egress-policy: block
22+
allowed-endpoints: >
23+
files.pythonhosted.org:443
24+
github.com:443
25+
pypi.org:443
26+
27+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
28+
with:
29+
# If it's a push (main or major-release) or workflow_dispatch, get full history.
30+
fetch-depth: ${{ (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && 0 || 1 }}
31+
32+
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
33+
with:
34+
python-version: '3.13'
35+
cache: pip
36+
37+
- uses: install-pinned/uv@259f91feb61b6e94766d7a1dbcd5f17335370e64
38+
39+
- run: |
40+
uv pip install --system -e .[all]
41+
uv pip install --system -r requirements-dev.txt
42+
43+
- name: configure git
44+
run: |
45+
git config user.name "github-actions"
46+
git config user.email "github-actions@github.com"
47+
48+
- uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306
49+
with:
50+
path: docs/html
51+
key: >-
52+
sphinx
53+
-${{ hashFiles('pyproject.toml') }}
54+
-${{ hashFiles('setup.py') }}
55+
-${{ hashFiles('requirements-dev.txt') }}
56+
-${{ hashFiles('docs/make.py') }}
57+
-${{ hashFiles('docs/conf.py') }}
58+
59+
- run: make build_docs
60+
working-directory: docs
61+
62+
- uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b
63+
with:
64+
path: docs/html/
65+
66+
deploy:
67+
needs: build
68+
# Only run this job if triggered by updating the main branch
69+
if: github.ref == 'refs/heads/main' && github.event_name == 'push'
70+
71+
runs-on: ubuntu-latest
72+
73+
permissions:
74+
pages: write
75+
id-token: write
76+
77+
environment:
78+
name: github-pages
79+
url: ${{ steps.deployment.outputs.page_url }}
80+
81+
steps:
82+
- uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
83+
with:
84+
disable-sudo: true
85+
egress-policy: audit
86+
87+
- uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e

‎.github/workflows/python-checks.yml‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -321,13 +321,44 @@ jobs:
321321
name: python-coverage-comment-action
322322
path: python-coverage-comment-action.txt
323323

324+
sphinx-lint:
325+
runs-on: ubuntu-latest
326+
327+
steps:
328+
- uses: step-security/harden-runner@e3f713f2d8f53843e71c69a996d56f51aa9adfb9
329+
with:
330+
disable-sudo: true
331+
egress-policy: block
332+
allowed-endpoints: >
333+
files.pythonhosted.org:443
334+
github.com:443
335+
pypi.org:443
336+
337+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
338+
339+
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
340+
with:
341+
python-version: '3.13'
342+
cache: pip
343+
344+
- uses: install-pinned/uv@259f91feb61b6e94766d7a1dbcd5f17335370e64
345+
346+
- run: |
347+
uv pip install --system -e .[all]
348+
uv pip install --system -r requirements-dev.txt
349+
350+
- run: sphinx-lint docs
351+
352+
- run: sphinx-lint parsons
353+
324354
pre-commit:
325355
runs-on: ubuntu-latest
326356

327357
needs:
358+
- bandit
328359
- ruff-format
329360
- ruff-check
330-
- bandit
361+
- sphinx-lint
331362

332363
permissions:
333364
contents: write

‎.pre-commit-config.yaml‎

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,27 @@
11
repos:
2+
- repo: https://github.com/pre-commit/pre-commit-hooks
3+
rev: v6.0.0
4+
hooks:
5+
- id: check-toml
6+
- id: check-yaml
7+
- id: end-of-file-fixer
8+
- id: trailing-whitespace
9+
210
- repo: https://github.com/astral-sh/ruff-pre-commit
3-
rev: v0.15.0
11+
rev: v0.15.6
412
hooks:
513
- id: ruff-check
6-
args: ['--fix']
14+
args: ['--fix']
715
- id: ruff-format
16+
817
- repo: https://github.com/PyCQA/bandit
9-
rev: 1.9.3
18+
rev: 1.9.4
1019
hooks:
1120
- id: bandit
1221
args: ['--confidence-level', 'medium', '--severity-level', 'medium', '--exclude', '**/vendor/*']
1322
files: '^parsons'
23+
24+
- repo: https://github.com/sphinx-contrib/sphinx-lint
25+
rev: v1.0.2
26+
hooks:
27+
- id: sphinx-lint

‎Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,4 +20,4 @@ RUN mkdir /app
2020
WORKDIR /app
2121

2222
# Useful for importing modules that are associated with your python scripts:
23-
ENV PYTHONPATH=.:/app
23+
ENV PYTHONPATH=.:/app

‎docs/Makefile‎

Lines changed: 11 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,16 @@
1-
# Minimal makefile for Sphinx documentation
2-
#
1+
PYTHON := python3
2+
SCRIPT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
3+
SCRIPT := $(SCRIPT_DIR)make.py
34

4-
# You can set these variables from the command line.
5-
SPHINXOPTS = -a
6-
SPHINXBUILD = sphinx-build
7-
SPHINXPROJ = Parsons
8-
SOURCEDIR = .
9-
BUILDDIR = .
5+
.PHONY: % check_python
106

11-
# Put it first so that "make" without argument is like "make help".
12-
help:
13-
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
7+
Makefile: ;
148

15-
deploy_docs:
16-
git branch latest
17-
git branch stable $$(git tag -l --sort=creatordate | tail -1)
18-
sphinx-multiversion . html
19-
cp ./index-redirect.html html/index.html
9+
%: check_python
10+
@$(PYTHON) "$(SCRIPT)" $@ $(filter-out $@,$(MAKECMDGOALS))
2011

21-
.PHONY: help Makefile
12+
check_python:
13+
@$(PYTHON) --version > /dev/null 2>&1 || (echo "Error: Python not found."; exit 1)
2214

23-
# Catch-all target: route all unknown targets to Sphinx using the new
24-
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
25-
%: Makefile
26-
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
15+
$(filter-out $(firstword $(MAKECMDGOALS)),$(MAKECMDGOALS)):
16+
@:

‎docs/_template.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,4 +36,3 @@ API
3636
.. autoclass:: parsons.yourconnector.yourconnector.YourConnector
3737
:inherited-members:
3838
:members:
39-

0 commit comments

Comments
 (0)