Update Boilerplate

.github/workflows/ci.yml

@@ -1,32 +1,91 @@
 name: Continuous Integration
 
+
 on:
   pull_request:
   push:
 
+
+env:
+  VALIDATE_PY_VERSION: "3.10"
+
+
 jobs:
 
-  test:
-    name: Test
+  Test:
     strategy:
       matrix:
         os: [ubuntu-latest, windows-latest]
         python: ["3.8", "3.9", "3.10"]
-    runs-on: "${{matrix.os}}"
-    env:
-      PY_COLORS: 1
+    runs-on: "${{ matrix.os }}"
     steps:
-      - {name: Check out repository code, uses: actions/checkout@v4}
-      - {name: Install Python, uses: actions/setup-python@v5, with: {python-version: "${{matrix.python}}"}, id: py}
-      - {name: Install Poetry, uses: abatilo/actions-poetry@v3}
-      - {name: Install dependencies, run: make deps}
-      - {name: Run lints, run: make lint}
-      - {name: Run tests, run: make test}
-      - {name: Run integration tests, run: make it}
-      - {name: Build docs, run: make docs}
-      - {name: Build package, run: make build}
-      - name: Upload coverage
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v3
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ matrix.python }}"
+          cache: poetry
+
+      - name: Install Dependencies
+        run: make deps
+
+      - name: Run Lints
+        run: make lint
+
+      - name: Run Tests
+        env:
+          PY_COLORS: 1
+        run: make test
+
+      - name: Run Integration Tests
+        run: make it
+
+      - name: Build Docs
+        run: make docs
+
+      - name: Build Package
+        run: make build
+
+      - name: Upload Coverage
         uses: codecov/codecov-action@v4
         with:
-          name: "coverage-${{runner.os}}-py${{steps.py.outputs.python-version}}"
+          name: "coverage-${{ runner.os }}-py${{ matrix.python }}"
           token: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload Artifact
+        if: runner.os == 'Linux' && matrix.python == env.VALIDATE_PY_VERSION
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          if-no-files-found: error
+
+  Validate:
+    needs: Test
+    runs-on: ubuntu-latest
+    steps:
+
+      - name: Download Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+
+      - name: Extract
+        run: |
+          ls -lah
+          unzip -t *.whl
+          unzip -p *.whl '*/METADATA'
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "${{ env.VALIDATE_PY_VERSION }}"
+
+      - name: Pip Install
+        run: pip install *.whl

.github/workflows/pypi.yml

@@ -5,30 +5,75 @@ on:
 
 jobs:
 
-  build:
-    name: Build
+  Docs:
     runs-on: ubuntu-latest
     steps:
-      - {name: Check out repository code, uses: actions/checkout@v4}
-      - {name: Install Python, uses: actions/setup-python@v5, with: {python-version: "3.10"}}
-      - {name: Install Poetry, uses: abatilo/actions-poetry@v3}
-      - {name: Copy LICENSE to COPYING, run: cp --no-clobber --verbose LICENSE COPYING}  # For Python wheel.
-      - {name: Build package, run: make build}
-      - name: Store artifacts
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v3
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: poetry
+      - name: Build Docs
+        run: make docs
+      - name: Compress
+        run: tar -C docs/_build -czvf docs.tar.gz --transform s/^html/docs/ html/
+      - name: Upload Artifact
         uses: actions/upload-artifact@v4
-        with: {name: dist, path: dist/, if-no-files-found: error}
+        with:
+          name: docs
+          path: docs.tar.gz
+          if-no-files-found: error
 
-  publish:
-    name: Publish to PyPI
-    needs: build
+  Build:
     runs-on: ubuntu-latest
     steps:
-      - {name: Fetch packages, uses: actions/download-artifact@v4, with: {name: dist, path: dist}}
-      - name: Publish packages to PyPI
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install Poetry
+        uses: abatilo/actions-poetry@v3
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: poetry
+      - name: Copy LICENSE to COPYING  # For Python wheel
+        run: cp --no-clobber --verbose LICENSE COPYING
+      - name: Build Package
+        run: make build
+      - name: Upload Artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+          if-no-files-found: error
+
+  Publish:
+    needs: [Build, Docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download Build Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Publish to PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}
-      - name: Upload packages to Release
+      - name: Download Documentation Artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: dist
+      - name: Upload to Release
         uses: svenstaro/upload-release-action@v2
-        with: {file: dist/*, file_glob: true, repo_token: "${{ secrets.GITHUB_TOKEN }}", tag: "${{ github.ref }}"}
+        with:
+          file: dist/*
+          file_glob: true
+          repo_token: ${{ secrets.GITHUB_TOKEN }}
+          tag: ${{ github.ref }}

.readthedocs.yaml

@@ -1,37 +1,17 @@
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
-
-# Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
+    python: "3.10"
+  jobs:
+    pre_create_environment:
+      - asdf plugin add poetry
+      - asdf install poetry latest
+      - asdf global poetry latest
+    post_install:
+      - VIRTUAL_ENV="$READTHEDOCS_VIRTUALENV_PATH" poetry install --with dev
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
-
-# Optionally build your docs in additional formats such as PDF and ePub
-# formats:
-#   - pdf
-#   - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements: [docs]
+  fail_on_warning: true

CONTRIBUTING.md

@@ -8,25 +8,23 @@ You may follow these steps if you wish to create a pull request. Fork the repo a
 in the project's directory run this if you're on macOS (requires [Homebrew](https://brew.sh)):
 
 ```bash
-brew install python@3.7
+brew install python
 brew install poetry  # More info: https://python-poetry.org
 make clean
-POETRY_VIRTUALENVS_IN_PROJECT=true poetry env use "$(brew --prefix)/opt/[email protected]/bin/python3"
 ```
 
 On Ubuntu (including Windows WSL2):
 
 ```bash
-sudo apt-get update && sudo apt-get install make python3-virtualenv python3.9
-curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py | python3 -
+sudo apt-get update && sudo apt-get install make python3-virtualenv python3
+curl -sSL https://install.python-poetry.org | python3 -
 make clean
-POETRY_VIRTUALENVS_IN_PROJECT=true poetry env use "$(which python3.9)"
 ```
 
 Then see if you can run lints and tests:
 
 ```bash
-make all
+make deps all
 ```
 
 ## Writing Tests

Makefile

@@ -1,56 +1,55 @@
 .DEFAULT_GOAL = help
 PROJECT_NAME = sphinx_disqus
-export POETRY_VIRTUALENVS_IN_PROJECT = true
 
 ## Dependencies
 
 poetry.lock: _HELP = Lock dependency versions to file
 poetry.lock:
 	poetry lock
 
+.PHONY: relock
+relock: _HELP = Delete and recreate poetry lock file
+relock:
+	rm -f poetry.lock && $(MAKE) poetry.lock
+
 .PHONY: deps
 deps: _HELP = Install project dependencies
 deps:
-	poetry install -E docs
-	poetry run python -V
-
-requirements.txt: _HELP = Generate development requirements.txt
-requirements.txt: poetry.lock
-	poetry export --dev --without-hashes -o $@
+	poetry install --with dev
 
 ## Testing
 
 .PHONY: lint
 lint: _HELP = Run linters
-lint: deps
+lint:
 	poetry check
 	poetry run black --check --color --diff .
-	poetry run flake8 --application-import-names $(PROJECT_NAME),tests
-	poetry run pylint $(PROJECT_NAME) tests docs/conf.py
+	poetry run flake8 --application-import-names $(PROJECT_NAME),docs,tests
+	poetry run pylint $(PROJECT_NAME) docs tests
 
 .PHONY: test
 test: _HELP = Run unit tests
-test: deps
+test:
 	poetry run pytest --cov=$(PROJECT_NAME) --cov-report=html --cov-report=xml tests/unit_tests
 
 .PHONY: testpdb
 testpdb: _HELP = Run unit tests and drop into the debugger on failure
-testpdb: deps
+testpdb:
 	poetry run pytest --pdb tests/unit_tests
 
 .PHONY: it
 it: _HELP = Run integration tests
-it: deps
+it:
 	poetry run pytest tests/integration_tests
 
 .PHONY: itpdb
 itpdb: _HELP = Run integration tests and drop into the debugger on failure
-itpdb: deps
+itpdb:
 	poetry run pytest --pdb tests/integration_tests
 
 .PHONY: all
 all: _HELP = Run linters, unit tests, integration tests, and builds
-all: lint test it docs build
+all: test it lint docs build
 
 ## Build
 
@@ -59,7 +58,7 @@ build: _HELP = Build Python package (sdist and wheel)
 build:
 	poetry build -n -vvv
 
-docs/_build/html/index.html: deps
+docs/_build/html/index.html::
 	poetry run sphinx-build -a -E -n -W docs $(@D)
 	@echo Documentation available here: $@
 
@@ -71,8 +70,8 @@ docs: docs/_build/html/index.html
 
 clean: _HELP = Remove temporary files
 clean:
-	rm -rfv *.egg-info/ *cache*/ .*cache*/ .coverage coverage.xml htmlcov/ dist/ docs/_build requirements.txt
-	find . -name __pycache__ -type d -exec rm -r {} +
+	rm -rfv *.egg-info/ *cache*/ .*cache*/ .coverage* coverage.xml htmlcov/ dist/ docs/_build/ requirements.txt
+	find . -path '*/.*' -prune -o -name __pycache__ -type d -exec rm -r {} +
 
 distclean: _HELP = Remove temporary files including virtualenv
 distclean: clean