diff --git a/.github/actions/set-dev-env/action.yml b/.github/actions/set-dev-env/action.yml index 7964b4365..9acd42332 100644 --- a/.github/actions/set-dev-env/action.yml +++ b/.github/actions/set-dev-env/action.yml @@ -1,3 +1,5 @@ +# Reusable action to set our PST development environment +# DO NOT use for release jobs since we cache dependencies name: Setup PST CI environment description: Create a PST dev environment diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 4e4de2d80..fbe4b5888 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -4,7 +4,7 @@ updates: - package-ecosystem: "github-actions" directory: "/" schedule: - interval: "weekly" + interval: "monthly" labels: - "tag: dependencies" - "tag: CI" @@ -12,7 +12,7 @@ updates: - package-ecosystem: "npm" directory: "/" schedule: - interval: "weekly" + interval: "monthly" labels: - "tag: dependencies" - "tag: javascript" diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 3f35053bb..09f368b60 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -1,3 +1,4 @@ +# Testing (pytest, a11y-tests), profiling, and coverage checks for PST name: continuous-integration # Concurrency group that uses the workflow name and PR number if available @@ -21,6 +22,9 @@ on: branches: - main pull_request: + branches: + - "*" + # allows this to be used as a composite action in other workflows workflow_call: # allow manual triggering of the workflow, while debugging workflow_dispatch: @@ -31,10 +35,12 @@ jobs: strategy: fail-fast: true matrix: + # https://github.com/actions/runner-images # macos-14==latest - # ubuntu-20.04==latest - os: ["ubuntu-latest", "ubuntu-24.04", "macos-14", "windows-latest"] - python-version: ["3.9", "3.10", "3.11", "3.12"] + # ubuntu-24.04==latest + # windows-2022==latest + os: ["ubuntu-latest", "ubuntu-22.04", "macos-14", "windows-latest"] + python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] sphinx-version: [""] include: # oldest Python version with the oldest Sphinx version @@ -58,12 +64,16 @@ jobs: runs-on: ${{ matrix.os }} steps: - name: "Checkout repository 🛎" - uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 with: python-version: ${{ matrix.python-version }} pandoc: true + - name: "Run tests ✅" shell: bash run: | @@ -77,119 +87,40 @@ jobs: else python -Im tox run -e compile-assets,i18n-compile,py$(echo ${{ matrix.python-version }} | tr -d .)-tests fi + - name: "Upload coverage data to GH artifacts 📤" if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest' && matrix.sphinx-version == 'dev' - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 with: name: coverage-data-${{ matrix.python-version }} path: .coverage if-no-files-found: ignore include-hidden-files: true - # Only run accessibility tests on the latest Python version (3.12) and Ubuntu - a11y-tests: - name: "a11y-tests (ubuntu-latest, 3.12)" - runs-on: ubuntu-latest - steps: - - name: "Checkout repository 🛎" - uses: actions/checkout@v4 - - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env - with: - python-version: ${{ env.DEFAULT_PYTHON_VERSION }} - pandoc: true - graphviz: true - - name: "Run accessibility tests with playwright 🎭" - # build PST, build docs, then run a11y-tests - run: python -Im tox run -m a11y - - # Build our docs (PST) on major OSes and check for warnings - build-site: - name: "build PST docs" - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, macos-latest, windows-latest] - python-version: ["3.12"] - include: - # oldest Python version with the oldest Sphinx version - - os: ubuntu-latest - python-version: "3.9" - sphinx-version: "6.1" - runs-on: ${{ matrix.os }} - steps: - - name: "Checkout repository 🛎" - uses: actions/checkout@v4 - - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env - with: - python-version: ${{ matrix.python-version }} - pandoc: true - graphviz: true - - name: "Build docs and check for warnings 📖" - shell: bash - run: | - # check if there is a specific Sphinx version to build with - # example substitution: tox run -e py39-sphinx61-docs - if [ -n "${{matrix.sphinx-version}}" ]; then - python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs - # build with the default Sphinx version - # example substitution: tox run -e py312-docs - else - python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs - fi - - # Run Lighthouse audits on the built site (kitchen-sink only) - lighthouse-audit: - needs: build-site - runs-on: ubuntu-latest - env: - DOCS_DIR: "audit" - steps: - - name: "Checkout repository 🛎" - uses: actions/checkout@v4 - - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env - with: - python-version: ${{ env.DEFAULT_PYTHON_VERSION }} - - name: "Copy kitchen sink to a tiny site" - run: | - mkdir -p ${{ env.DOCS_DIR }}/site - cp -r docs/examples/kitchen-sink ${{ env.DOCS_DIR }}/site/kitchen-sink - printf "Test\n====\n\n.. toctree::\n\n kitchen-sink/index\n" > ${{ env.DOCS_DIR }}/site/index.rst - echo 'html_theme = "pydata_sphinx_theme"' > ${{ env.DOCS_DIR }}/site/conf.py - echo '.. toctree::\n :glob:\n\n *' >> ${{ env.DOCS_DIR }}/site/index.rst - - # build docs without checking for warnings - python -Im tox run -e docs-no-checks - - - name: "Audit with Lighthouse 🔦" - uses: treosh/lighthouse-ci-action@v12 - with: - configPath: ".github/workflows/lighthouserc.json" - temporaryPublicStorage: true - uploadArtifacts: true - runs: 3 # Multiple runs to reduce variance - coverage: name: "Check coverage" needs: run-pytest runs-on: ubuntu-latest - # avoid running this on schedule, releases, or workflow_call - if: github.event_name != 'schedule' && github.event_name != 'release' && github.event_name != 'workflow_call' + # avoid running this on schedule, releases, workflow_call, or workflow_dispatch + if: github.event_name != 'schedule' && github.event_name != 'release' && github.event_name != 'workflow_call' && github.event_name != 'workflow_dispatch' permissions: contents: write pull-requests: write steps: - name: "Checkout repository 🛎" - uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 with: python-version: ${{ env.DEFAULT_PYTHON_VERSION }} + - run: python -Im pip install --upgrade coverage[toml] + - name: "Download coverage data 📥" - uses: actions/download-artifact@v4 + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 with: pattern: coverage-data-* merge-multiple: true @@ -207,7 +138,7 @@ jobs: python -Im coverage report --fail-under=80 - name: "Upload HTML report if check failed 📤" - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 with: name: html-report path: htmlcov @@ -215,13 +146,13 @@ jobs: # seems we need to call this from the main CI workflow first - name: "Coverage comment 💬" - uses: py-cov-action/python-coverage-comment-action@v3 + uses: py-cov-action/python-coverage-comment-action@b2eb38dd175bf053189b35f738f9207278b00925 id: coverage_comment with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: "Store Pull Request comment to be posted 📤" - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 if: steps.coverage_comment.outputs.COMMENT_FILE_WRITTEN == 'true' with: # leave default names @@ -229,23 +160,38 @@ jobs: path: python-coverage-comment-action.txt profiling: - needs: [build-site, run-pytest] + needs: [run-pytest] runs-on: ubuntu-latest steps: - name: "Checkout repository 🛎" - uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 with: # 3.12 is not supported by py-spy yet python-version: "3.11" + - name: "Run profiling with py-spy 🕵️‍♂️" # profiling needs to be run as sudo run: python -m tox run -e py311-profile-docs -- -o docbuild_profile.svg continue-on-error: true + - name: "Upload profiling data to GH artifacts 📤" - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 with: name: profile-results path: docbuild_profile.svg if-no-files-found: ignore + + # Calling the coverage-comment action from the main CI workflow + # we might want to pin the SHA once merged + coverage-comment: + uses: ./.github/workflows/coverage.yml + needs: [coverage] + permissions: + contents: write + pull-requests: write + actions: read diff --git a/.github/workflows/a11y.yml b/.github/workflows/a11y.yml new file mode 100644 index 000000000..0aacd803a --- /dev/null +++ b/.github/workflows/a11y.yml @@ -0,0 +1,54 @@ +name: a11y-tests + +# Concurrency group that uses the workflow name and PR number if available +# or commit SHA as a fallback. If a new build is triggered under that +# concurrency group while a previous build is running it will be canceled. +# Repeated pushes to a PR will cancel all previous builds, while multiple +# merges to main will not cancel. +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: true + +env: + FORCE_COLOR: "1" # Make tools pretty + DEFAULT_PYTHON_VERSION: "3.12" # keep in sync with tox.ini + PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates + +permissions: {} + +on: + push: + branches: + - main + pull_request: + branches: + - "*" + # allows this to be used as a composite action in other workflows + workflow_call: + # allow manual triggering of the workflow, while debugging + workflow_dispatch: + +jobs: + a11y-tests: + strategy: + fail-fast: true + matrix: + os: ["ubuntu-latest", "ubuntu-22.04", "macos-14", "windows-latest"] + browser: ["firefox", "chromium"] + runs-on: ${{ matrix.os }} + steps: + - name: "Checkout repository 🛎" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + + - name: "Setup CI environment 🛠" + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 + with: + python-version: ${{ env.DEFAULT_PYTHON_VERSION }} + pandoc: true + graphviz: true + + - name: "Run accessibility tests with playwright 🎭" + # build PST, build docs, then run a11y-tests + run: python -Im tox run -e compile-assets,i18n-compile,py312-docs,a11y-tests -- --browser ${{ matrix.browser }} diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index 06d2bb69b..bd2673183 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -1,14 +1,11 @@ name: Post coverage comment on: - workflow_run: - workflows: ["continuous-integration"] - types: - - completed + workflow_call: jobs: test: - name: "Run tests & display coverage" + name: "Display code coverage" runs-on: ubuntu-latest if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' permissions: @@ -18,15 +15,17 @@ jobs: steps: - name: "Get the triggering workflow run details" id: get-run - uses: octokit/request-action@v2.x + uses: octokit/request-action@dad4362715b7fb2ddedf9772c8670824af564f0d with: - route: GET /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }} + route: GET /repos/"${REPO}"/actions/runs/"${WORKFLOW_RUN_ID}" env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + REPO: ${{ github.repository }} + WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }} # this needs the .coverage file so we download from the CI workflow artifacts - name: "Download coverage data 📥" - uses: actions/download-artifact@v4 + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 with: pattern: coverage-data-* merge-multiple: true @@ -37,7 +36,7 @@ jobs: run: ls -R - name: "Post coverage comment" - uses: py-cov-action/python-coverage-comment-action@v3 + uses: py-cov-action/python-coverage-comment-action@b2eb38dd175bf053189b35f738f9207278b00925 with: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..1830d678b --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,131 @@ +# This workflow is checks that the documentation can be built across multiple OSes, Python, and Sphinx versions. +# It also checks for broken links in the documentation and runs Lighthouse audits on the built site. + +name: docs-checks + +# Concurrency group that uses the workflow name and PR number if available +# or commit SHA as a fallback. If a new build is triggered under that +# concurrency group while a previous build is running it will be canceled. +# Repeated pushes to a PR will cancel all previous builds, while multiple +# merges to main will not cancel. +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }} + cancel-in-progress: true + +env: + FORCE_COLOR: "1" # Make tools pretty + DEFAULT_PYTHON_VERSION: "3.12" # keep in sync with tox.ini + PIP_DISABLE_PIP_VERSION_CHECK: "1" # Don't check for pip updates + +on: + push: + branches: + - main + pull_request: + branches: + - "*" + # allows this to be used as a composite action in other workflows + workflow_call: + # allow manual triggering of the workflow, while debugging + workflow_dispatch: + +jobs: + # Build our docs (PST) on major OSes and check for warnings + build-site: + name: "build PST docs" + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + python-version: ["3.12", "3.13"] + include: + # oldest Python version with the oldest Sphinx version + - os: ubuntu-latest + python-version: "3.9" + sphinx-version: "6.1" + runs-on: ${{ matrix.os }} + steps: + - name: "Checkout repository 🛎" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + + - name: "Setup CI environment 🛠" + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 + with: + python-version: ${{ matrix.python-version }} + pandoc: true + graphviz: true + + - name: "Build docs and check for warnings 📖" + shell: bash + run: | + # check if there is a specific Sphinx version to build with + # example substitution: tox run -e py39-sphinx61-docs + if [ -n "${{matrix.sphinx-version}}" ]; then + python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-sphinx$(echo ${{ matrix.sphinx-version }} | tr -d .)-docs + # build with the default Sphinx version + # example substitution: tox run -e py312-docs + else + python -Im tox run -e py$(echo ${{ matrix.python-version }} | tr -d .)-docs + fi + + # Run Lighthouse audits on the built site (kitchen-sink only) + lighthouse-audit: + needs: build-site + runs-on: ubuntu-latest + steps: + - name: "Checkout repository 🛎" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + + - name: "Setup CI environment 🛠" + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 + with: + python-version: ${{ env.DEFAULT_PYTHON_VERSION }} + + - name: "Copy kitchen sink to a tiny site" + run: | + # ensuring proper scaping of the variable + docs_dir="${DOCS_DIR}" + mkdir -p $docs_dir/site + cp -r docs/examples/kitchen-sink $docs_dir/site/kitchen-sink + printf "Test\n====\n\n.. toctree::\n\n kitchen-sink/index\n" > $docs_dir/site/index.rst + echo 'html_theme = "pydata_sphinx_theme"' > $docs_dir/site/conf.py + echo '.. toctree::\n :glob:\n\n *' >> $docs_dir/site/index.rst + + # build docs without checking for warnings + python -Im tox run -e docs-no-checks + env: + DOCS_DIR: "audit" + + - name: "Audit with Lighthouse 🔦" + uses: treosh/lighthouse-ci-action@v12 + with: + configPath: ".github/workflows/lighthouserc.json" + temporaryPublicStorage: true + uploadArtifacts: true + runs: 3 # Multiple runs to reduce variance + + # Check for broken links in our docs + link-check: + runs-on: ubuntu-latest + steps: + - name: "Checkout repository 🛎" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + + - name: "Setup CI environment 🛠" + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 + + - name: "Check for broken links 🔗" + run: python -Im tox -e docs-linkcheck + + - name: "Upload file with broken links 📤" + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 + with: + name: broken-links + path: docs/_build/linkcheck/output.txt + if: ${{ always() }} diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml index 4343c959c..c6bcdb8f4 100644 --- a/.github/workflows/prerelease.yml +++ b/.github/workflows/prerelease.yml @@ -13,27 +13,35 @@ env: jobs: prerelease: + # only run this workflow for pydata owned repositories (avoid forks) + if: github.repository_owner == 'pydata' runs-on: ubuntu-latest strategy: fail-fast: false matrix: - python-version: ["3.9", "3.10", "3.11", "3.12"] + python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"] steps: - name: "Checkout repository 🛎" - uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env + uses: pydata/pydata-sphinx-theme/.github/actions/set-dev-env@01731d0cc57768b9eff1c97f38909932ecd7e7d1 with: python-version: ${{ matrix.python-version }} pandoc: true + - name: "Install (prerelease) dependencies 📦" run: | python -Im pip install --upgrade pip wheel setuptools + - name: "Build PST docs and check for warnings 📖" run: | # example substitution: tox run -e docs-py312-docs python -Im tox run -e docs-py$(echo ${{ matrix.python-version }} | tr -d .)-docs -- --keep-going + - name: "Run tests ✅ (no coverage)" run: | # this will compile the assets then run the tests @@ -41,12 +49,14 @@ jobs: echo "PYTEST_ERRORS=$?" >> $GITHUB_ENV - name: "Build and inspect package 📦" - uses: hynek/build-and-inspect-python-package@v2 + uses: hynek/build-and-inspect-python-package@14c7e53f5d033cfa99f7af916fa59a6f7f356394 if: matrix.python-version == '3.9' id: baipp - - run: echo Packages can be found at ${{ steps.baipp.outputs.dist }} + - run: echo Packages can be found at "${BAIPP_DIST}" if: matrix.python-version == '3.9' + env: + BAIPP_DIST: ${{ steps.baipp.outputs.dist }} # If either the docs build or the tests resulted in an error, create an issue to note it - name: "Create an issue if failure" diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 16f400365..303a8c399 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -1,7 +1,6 @@ -# This will run every time a release is created and published. -# It calls our tests workflow via a `workflow_call`, and if tests pass -# then it triggers our upload to PyPI for a new release. -name: Publish to PyPI +# This workflow runs every day at 2AM UTC to publish a new nightly release to Anaconda.org +# and every time there is a PST release to make sure it gets uploaded to PyPI. +name: Publish PST package on: release: types: @@ -17,42 +16,54 @@ permissions: contents: read jobs: - # calls our general CI workflow (tests, build docs, etc.) + # calls our general CI workflows (tests, coverage, profile, etc.) tests: uses: ./.github/workflows/CI.yml # needed for the coverage action permissions: contents: write pull-requests: write + # calls our docs workflow (build docs, check broken links, lighthouse) + docs: + uses: ./.github/workflows/docs.yml build-package: name: "Build & verify PST package" - needs: [tests] # require tests to pass before deploy runs + # require tests and docs to pass before building the package + needs: [tests, docs] runs-on: ubuntu-latest steps: - name: "Checkout repository 🛎" - uses: actions/checkout@v4 + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # 4.2.2 + with: + persist-credentials: false - - name: "Setup CI environment 🛠" - uses: ./.github/actions/set-dev-env + - name: "Setup Python 🐍" + uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # 5.3.0 with: python-version: "3.9" - pandoc: "False" + + - run: python -Im pip install tox-uv - name: "Build and inspect package 📦" - uses: hynek/build-and-inspect-python-package@v2 + uses: hynek/build-and-inspect-python-package@14c7e53f5d033cfa99f7af916fa59a6f7f356394 # 2.11.0 id: baipp - - run: echo Packages can be found at ${{ steps.baipp.outputs.dist }} + - run: echo Packages can be found at "${BAIPP_DIST}" + env: + BAIPP_DIST: ${{ steps.baipp.outputs.dist }} - release-pypi: + release-PST: runs-on: ubuntu-latest needs: [build-package] permissions: id-token: write # needed for PyPI upload + environment: + name: pst-release + url: https://pypi.org/p/pydata-sphinx-theme steps: - name: "Download PST built package 📦" - uses: actions/download-artifact@v4 + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # 4.1.8 with: name: Packages path: dist @@ -62,9 +73,11 @@ jobs: tar xvf dist/*.tar.gz --strip-components=1 - name: "Publish PST package to PyPI 🚀" - uses: pypa/gh-action-pypi-publish@release/v1 + uses: pypa/gh-action-pypi-publish@67339c736fd9354cd4f8cb0b744f2b82a74b5c70 # 1.12.3 # only publish if this is a published release by pydata if: github.repository_owner == 'pydata' && github.event_name == 'release' && github.event.action == 'published' + with: + print-hash: true - name: "Publish PST package to scientific-python-nightly-wheels 🚀" uses: scientific-python/upload-nightly-action@82396a2ed4269ba06c6b2988bb4fd568ef3c3d6b # 0.6.1 diff --git a/.github/workflows/zizmor.yml b/.github/workflows/zizmor.yml new file mode 100644 index 000000000..4199bca0e --- /dev/null +++ b/.github/workflows/zizmor.yml @@ -0,0 +1,40 @@ +# Performs static analysis in GitHub actions with https://github.com/woodruffw/zizmor +name: Zizmor + +on: + push: + branches: + - main + pull_request: + branches: + - "*" + +permissions: + contents: read + +jobs: + zizmor: + name: "Run Zizmor" + runs-on: ubuntu-latest + permissions: + security-events: write + steps: + - name: "Checkout repository 🛎" + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 + with: + persist-credentials: false + + - name: "Install uv 📦" + uses: astral-sh/setup-uv@887a942a15af3a7626099df99e897a18d9e5ab3a + + - name: "Run zizmor 🕵️‍♂️" + run: uvx zizmor --format sarif . > results.sarif + + - name: "Upload SARIF file 📤" + uses: github/codeql-action/upload-sarif@v3 + with: + # Path to SARIF file relative to the root of the repository + sarif_file: results.sarif + # Optional category for the results + # Used to differentiate multiple results for one commit + category: zizmor diff --git a/docs/community/design-system.md b/docs/community/design-system.md index 4c6634d42..edb380c1e 100644 --- a/docs/community/design-system.md +++ b/docs/community/design-system.md @@ -178,8 +178,8 @@ color and typography in the PyData Sphinx theme: 1. [https://carbondesignsystem.com/elements/typography/overview/](https://carbondesignsystem.com/elements/typography/overview/) 2. [https://canvas.workday.com/styles/tokens/type](https://canvas.workday.com/styles/tokens/type) 3. [https://atlassian.design/foundations/typography-beta](https://atlassian.design/foundations/typography-beta) - refer to the [Figma Design File](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-160). + refer to the [Figma Design File](https://www.figma.com/community/file/1443191723065200671/pydata-sphinx-theme-design-system). -[figma-library]: https://www.figma.com/community/file/1443191723065200671 +[figma-library]: https://www.figma.com/community/file/1443191723065200671/pydata-sphinx-theme-design-system diff --git a/docs/community/inspiration.md b/docs/community/inspiration.md index 91f017d1d..ebf4a3b30 100644 --- a/docs/community/inspiration.md +++ b/docs/community/inspiration.md @@ -26,5 +26,5 @@ When making new decisions about design and UI/UX, we often consult these themes image: https://d33wubrfki0l68.cloudfront.net/c088b7acfcf11100903c44fe44f2f2d7e0f30531/47727/img/docusaurus.svg - title: "**Material for MkDocs**" link: https://squidfunk.github.io/mkdocs-material/getting-started/ - image: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/src/.icons/logo.svg + image: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/logo.svg ``` diff --git a/docs/community/setup.md b/docs/community/setup.md index f14961070..7f33ccd49 100644 --- a/docs/community/setup.md +++ b/docs/community/setup.md @@ -29,7 +29,7 @@ time. ## Workflow for contributing changes -We follow a [typical GitHub workflow](https://guides.github.com/introduction/flow/) +We follow a [typical GitHub workflow](https://docs.github.com/en/get-started/using-github/github-flow) of: - create a personal fork and local clone of this repo @@ -50,7 +50,7 @@ First off you'll need your copy of the `pydata-sphinx-theme` codebase. You can clone it for local development like so: 1. **Fork the repository**, so you have your own copy on GitHub. - See [the GitHub forking guide](https://docs.github.com/en/get-started/quickstart/fork-a-repo) for more information. + See [the GitHub forking guide](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) for more information. 2. **Clone the repository locally** so that you have a local copy to work from: ```console diff --git a/docs/community/topics/accessibility.md b/docs/community/topics/accessibility.md index c22e4724b..f2df1300b 100644 --- a/docs/community/topics/accessibility.md +++ b/docs/community/topics/accessibility.md @@ -58,6 +58,7 @@ of three pages from the theme docs. We collected those findings in an issue on GitHub, [May 2024 PyData Theme audit findings](https://github.com/Quansight-Labs/czi-scientific-python-mgmt/issues/72) -Nearly all of the issues have been fixed, but of course things do break / have +Nearly all the issues have been fixed, but naturally course things do break / have already broken, and some things may have never been discovered, so please -[create a GitHub issue](https://github.com/pydata/pydata-sphinx-theme/issues/new) if you find something inaccessible. +[create a GitHub issue](https://github.com/pydata/pydata-sphinx-theme/issues) if you +find something inaccessible. diff --git a/docs/community/topics/assets.md b/docs/community/topics/assets.md index 848da625a..6c9721be3 100644 --- a/docs/community/topics/assets.md +++ b/docs/community/topics/assets.md @@ -48,9 +48,9 @@ the only `vendored` font. ## Jinja macros -Our Webpack build generates a collection of [Jinja macros](https://jinja.palletsprojects.com/en/3.0.x/templates/#macros) in the `static/webpack-macros.html` file. +Our Webpack build generates a collection of [Jinja macros](https://jinja.palletsprojects.com/en/stable/templates/) in the `static/webpack-macros.html` file. These macros are imported in the main `layout.html` file, and then inserted at various places on the page to link the static assets. -Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're needed. +Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preload), meaning that the browser begins requesting these resources before they're needed. In particular, our JavaScript assets are preloaded in ``, and the scripts are loaded at the end of ``. diff --git a/docs/community/topics/i18n.rst b/docs/community/topics/i18n.rst index b340a0b60..8081cac5a 100644 --- a/docs/community/topics/i18n.rst +++ b/docs/community/topics/i18n.rst @@ -68,10 +68,10 @@ Any text that is marked in this way will be discoverable by ``pybabel`` and used Once you've marked the text as localizable, complete the steps outlined in the :ref:`updating-localization-files` section of this documentation. -For more details on marking strings as localizable in jinja templates visit `the Jinja2 documentation `__. +For more details on marking strings as localizable in jinja templates visit `the Jinja2 documentation `__. .. tip:: - Remember to `manually escape variables `__ if needed. + Remember to `manually escape variables `__ if needed. Sometimes, it can help localizers to describe where a string comes from or whether it refers to a noun or verb, particularly if it can be difficult to find in the theme, or if the string itself is not very self-descriptive (for example, very short strings). @@ -174,7 +174,7 @@ We manage localizations on the `PyData Sphinx Theme project on Transifex `__. +#. Sign up for a `Transifex account `__. #. Join the `PyData Sphinx Theme project `__. #. Select the language you want to localize. If the language you are looking for is not listed, you can `open an issue on GitHub to request it `__. Then you can open a pull request to add the new language following the steps outlined in :ref:`adding-new-language`. diff --git a/docs/conf.py b/docs/conf.py index afab8132c..0161fab35 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -334,3 +334,46 @@ def setup(app: Sphinx) -> Dict[str, Any]: "parallel_read_safe": True, "parallel_write_safe": True, } + + +linkcheck_anchors_ignore = [ + # match any anchor that starts with a '/' since this is an invalid HTML anchor + r"\/.*", +] + +linkcheck_ignore = [ + # The crawler gets "Anchor not found" for various anchors + r"https://github.com.+?#.*", + r"https://www.sphinx-doc.org/en/master/*/.+?#.+?", + # Known broken links in kitchen sink + r"https://source.unsplash.com/.+", + # sample urls + "http://someurl/release-0.1.0.tar-gz", + "http://python.py", + # for whatever reason the Ablog index is treated as broken + "../examples/blog/index.html", + # get a 403 on CI + "https://canvas.workday.com/styles/tokens/type", + "https://unsplash.com/", +] + +linkcheck_allowed_redirects = { + r"http://www.python.org": "https://www.python.org/", + # :source:`something` linking files in the repository + r"https://github.com/pydata/pydata-sphinx-theme/tree/.*": r"https://github.com/pydata/pydata-sphinx-theme/blob/.*", + r"https://github.com/sphinx-themes/sphinx-themes.org/raw/.*": r"https://github.com/sphinx-themes/sphinx-themes.org/tree/.*", + # project redirects + r"https://pypi.org/project/[A-Za-z\d_\-\.]+/": r"https://pypi.org/project/[a-z\d\-\.]+/", + r"https://virtualenv.pypa.io/": "https://virtualenv.pypa.io/en/latest/", + # catching redirects in rtd + r"https://[A-Za-z\d_\-\.]+.readthedocs.io/": r"https://[A-Za-z\d_\-\.]+\.readthedocs\.io(/en)?/(stable|latest)/", + r"https://readthedocs.org/": r"https://about.readthedocs.com\?ref=readthedocs.org", + r"https://app.readthedocs.org/dashboard/": r"https://app.readthedocs.org/accounts/login/\?next=/dashboard/", + # miscellanenous urls + r"https://python.arviz.org/": "https://python.arviz.org/en/stable/", + r"https://www.sphinx-doc.org/": "https://www.sphinx-doc.org/en/master/", + r"https://idtracker.ai/": "https://idtracker.ai/latest/", + r"https://gitlab.com": "https://about.gitlab.com/", + r"http://www.yahoo.com": "https://www.yahoo.com/", + r"https://feature-engine.readthedocs.io/": "https://feature-engine.trainindata.com/en/latest/", +} diff --git a/docs/user_guide/accessibility.md b/docs/user_guide/accessibility.md index 11f63b516..59d995017 100644 --- a/docs/user_guide/accessibility.md +++ b/docs/user_guide/accessibility.md @@ -128,7 +128,7 @@ Most major browsers, including Firefox and Chrome, have built-in accessibility tools as part of their web developer tools. These tools can help to quickly identify accessibility issues and often include links to standards: -- [Firefox Accessibility Inspector](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector) +- [Firefox Accessibility Inspector](https://firefox-source-docs.mozilla.org/devtools-user/accessibility_inspector/index.html) - [Chrome DevTools Accessibility](https://developer.chrome.com/docs/devtools/accessibility/reference) There are also a few browser extensions that some of the maintainers of this diff --git a/docs/user_guide/fonts.rst b/docs/user_guide/fonts.rst index 8a29c8e83..ebdc137f6 100644 --- a/docs/user_guide/fonts.rst +++ b/docs/user_guide/fonts.rst @@ -48,10 +48,10 @@ The default body and header fonts can be changed as follows: {% endblock %} Your text may quickly show up as "unstyled" before the fonts are loaded. To reduce this, you may wish to explore options for - `preloading content `__, + `preloading content `__, specifically the binary font files. This ensures the files will be loaded before the CSS is parsed, but should be used with care. -.. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/ +.. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/assets/styles/variables .. _pydata-css-colors: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss .. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst index ed99cbaf4..8a5564879 100644 --- a/docs/user_guide/styling.rst +++ b/docs/user_guide/styling.rst @@ -2,7 +2,7 @@ Theme variables and CSS ======================= -.. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/ +.. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/tree/main/src/pydata_sphinx_theme/assets/styles/variables .. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties This section covers a few ways that you can control the look and feel of your theme via your own CSS and theme variables. diff --git a/pyproject.toml b/pyproject.toml index f8b2eb2ae..ec23953f5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [build-system] requires = [ - "sphinx-theme-builder @ https://github.com/pradyunsg/sphinx-theme-builder/archive/87214d0671c943992c05e3db01dca997e156e8d6.zip", + "sphinx-theme-builder @ git+https://github.com/pradyunsg/sphinx-theme-builder.git@main" ] build-backend = "sphinx_theme_builder" @@ -108,7 +108,7 @@ indent-width = 4 ignore = [ "D107", # Missing docstring in `__init__` | set the docstring in the class "D205", # 1 blank line required between summary line and description, - "D212", # docstring summary must be on first physical line + "D212", # docstring summary must be on first physical line "W291", # let pre-commit handle trailing whitespace ] diff --git a/tox.ini b/tox.ini index ac4f17675..34017556b 100644 --- a/tox.ini +++ b/tox.ini @@ -41,7 +41,6 @@ commands = # can substitute the target directory with any other directory by calling: # tox run -e docs-no-checks -- path/to/other/directory docs-no-checks: sphinx-build {posargs:audit}/site {posargs:audit}/_build - docs-linkcheck: sphinx-build -W -b linkcheck docs/ docs/_build/html --keep-going # example tox run -e py39-profile-docs -- -o profile.svg -n 100 profile-docs: python ./tools/profile.py {posargs} @@ -77,6 +76,8 @@ commands = # run accessibility tests with Playwright and axe-core # compiling the assets is needed before running the tests # tox run -e compile,py312-docs,a11y-tests +# to specify the browser: +# tox run -e compile,py312-docs,a11y-tests -- --browser=firefox [testenv:a11y-tests] description = run accessibility tests with Playwright and axe-core base_python = py312 # keep in sync with tests.yml @@ -108,7 +109,7 @@ extras = {[testenv:docs-no-checks]extras} deps = py39-sphinx61-docs: sphinx~=6.1.0 commands = - sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt {posargs} + sphinx-build -b html docs/ docs/_build/html -v -w warnings.txt python tests/utils/check_warnings.py # recommended for local development, this command will build the PST documentation @@ -136,13 +137,23 @@ extras = dev package = editable deps = - sphinx-theme-builder[cli]@git+https://github.com/pradyunsg/sphinx-theme-builder#egg=d9f620b + sphinx-theme-builder[cli] @ git+https://github.com/pradyunsg/sphinx-theme-builder.git@main # suppress Py3.11's new "can't debug frozen modules" warning set_env = PYDEVD_DISABLE_FILE_VALIDATION=1 commands = docs-live-theme: stb serve docs --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db docs-live: sphinx-autobuild docs/ docs/_build/html --open-browser --re-ignore=locale|api|_build|\.jupyterlite\.doit\.db +# check external links in the documentation +# tox run -e docs-linkcheck +[testenv:docs-linkcheck] +description = "Check external links in the documentation" +extras = {[testenv:docs-no-checks]extras} +allowlist_externals = bash +commands = + sphinx-build -b linkcheck docs/ docs/_build/linkcheck -w warnings.txt --keep-going -q + bash -c "echo 'Linkcheck complete; see docs/_build/linkcheck/output.txt for any errors'" + # extract translatable files into the POT file and update locale PO files # tox run -e i18n-extract # this will update all locales, to update a single locale you can @@ -172,10 +183,9 @@ commands = # compile translation catalogs to binary MO files # tox run -e i18n-compile -# tox run -e i18n-compile -- --use-fuzzy [testenv:i18n-compile] description = "Compile translation catalogs to binary MO files" extras = {[testenv:i18n-extract]extras} package = editable commands = - pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx {posargs} + pybabel compile -d src/pydata_sphinx_theme/locale -D sphinx