From 7a9c8dd26965f21eca42fb28b77ed0574b894532 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:10:00 -0700 Subject: [PATCH 1/7] docs(sphinx): add empty _static directory to prevent future warnings --- docs/_static/.gitignore | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/.gitignore diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore new file mode 100644 index 0000000..e69de29 From e28daa2c24707b621b881a9dd76942e3c3bab2b9 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:10:29 -0700 Subject: [PATCH 2/7] docs(sphinx): ignore all files in _static to prevent accidental adds --- docs/_static/.gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/_static/.gitignore b/docs/_static/.gitignore index e69de29..72e8ffc 100644 --- a/docs/_static/.gitignore +++ b/docs/_static/.gitignore @@ -0,0 +1 @@ +* From c79b8b7dceb93631d82bccd66e53b9d01e09bd60 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:10:51 -0700 Subject: [PATCH 3/7] chore(gitignore): ignore sphinx output --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index cc6eb80..f413420 100644 --- a/.gitignore +++ b/.gitignore @@ -42,6 +42,7 @@ htmlcov/ # Sphinx docs/_build +docs/_output # Cursor .cursorrules From 850b17b67abe13570290778e12d17ac53cae294f Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:13:49 -0700 Subject: [PATCH 4/7] build(script): added docs script for building with rtd process --- script/docs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100755 script/docs diff --git a/script/docs b/script/docs new file mode 100755 index 0000000..4423a03 --- /dev/null +++ b/script/docs @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +# This script will install the project and all its dependencies into a virtual +# environment and then build the documentation. +# +# It maintains parity with the Read the Docs build process. + +# Use a separate venv from the main development venv +# shellcheck disable=SC2034 +UV_PROJECT_ENVIRONMENT="${UV_PROJECT_ENVIRONMENT:-./docs/.venv/}" + +# Create a virtual environment for the documentation +uv venv "${UV_PROJECT_ENVIRONMENT}" + +# Install the project and all its dependencies into the virtual environment +uv sync --frozen --all-extras --all-groups --no-editable --link-mode=copy +uv pip install --link-mode=copy . + +# Build the documentation, failing on warnings +uv run python -m sphinx -T -W --keep-going -b html -d ./docs/_build/doctrees -D language=en ./docs ./docs/_output From 33e375c2ea359d182397807696d24a3733b18ac3 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:14:26 -0700 Subject: [PATCH 5/7] chore(pyproject): added setuptools explicit package to avoid build errors on pip install --- pyproject.toml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 940150c..261963c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ name = "pytool" version = "6.0.1" description = "Pytool is a collection of utilities and language enhancements for Python" readme = "README.md" -license = {text = "MIT"} +license = "MIT" authors = [ {name = "Jacob Alheid", email = "shakefu@gmail.com"}, ] @@ -30,3 +30,7 @@ docs = [ "sphinx-rtd-theme >=2.0.0, <3.0.0", "sphinx-autodoc-typehints >=1.25.2, <2.0.0", ] + +# This is required so setuptools doesn't see "script" as a package +[tool.setuptools] +packages = ["pytool"] From fb8b3312bdb2e1d6d6264dd14bb1eb90b3227c26 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:14:57 -0700 Subject: [PATCH 6/7] fix(json): updated as_json docstring to fix sphinx error --- pytool/json.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pytool/json.py b/pytool/json.py index 315503e..6eed0bf 100644 --- a/pytool/json.py +++ b/pytool/json.py @@ -57,8 +57,8 @@ def as_json(obj, **kwargs): :class:`bson.ObjectId`. :param object obj: An object to encode. - :param \*\*kwargs: Any optional keyword arguments to pass to the \ - JSONEncoder + :param kwargs: Any optional keyword arguments to pass to the \ + JSONEncoder :returns: JSON encoded version of `obj`. .. versionadded:: 2.4 From eb5eeb46ef391b3a0c6f05da4179b5fd6784cbf0 Mon Sep 17 00:00:00 2001 From: Jacob Alheid Date: Mon, 9 Jun 2025 15:18:10 -0700 Subject: [PATCH 7/7] ci(docs): add docs job to make sure docs build successfully --- .github/workflows/ci.yaml | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index fe2f739..17a8e57 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -86,9 +86,28 @@ jobs: uv run pytest --cov uv run coveralls + docs: + name: Docs + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4 + - uses: actions/setup-python@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # v5 + with: + python-version-file: ".python-version" + - uses: astral-sh/setup-uv@f0ec1fc3b38f5e7cd731bb6ce540c5af426746bb # v6.1.0 + with: + version: "0.7.12" + enable-cache: true + cache-dependency-glob: "pyproject.toml" + - env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Build docs + uv run script/docs + checks: name: Checks - needs: [lint, test] + needs: [lint, test, docs] runs-on: ubuntu-latest permissions: issues: write