Add new ruff-format-docs hook

.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    name: pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install pre-commit
+        run: uv sync --group lint
+
+      - name: Cache pre-commit
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+
+      - name: Run pre-commit
+        run: |
+          echo '```console' > "$GITHUB_STEP_SUMMARY"
+          # Enable color output for pre-commit and remove it for the summary
+          # Use --hook-stage=manual to enable slower pre-commit hooks that are skipped by default
+          uv run pre-commit run --all-files --show-diff-on-failure --color=always --hook-stage=manual | \
+            tee >(sed -E 's/\x1B\[([0-9]{1,2}(;[0-9]{1,2})*)?[mGK]//g' >> "$GITHUB_STEP_SUMMARY") >&1
+          exit_code="${PIPESTATUS[0]}"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          exit "$exit_code"
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group test
+
+      - name: Run tests
+        run: uv run pytest --cov=.

.github/workflows/main.yml

@@ -15,6 +15,8 @@ jobs:
         run: sleep 30
 
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
 
       - name: Install uv
         uses: astral-sh/setup-uv@v5
@@ -32,10 +34,10 @@ jobs:
           UNPUSHED_COMMITS=$(git log origin/main..HEAD)
           if [ -z "$UNPUSHED_COMMITS" ]; then
             echo "No unpushed commits found."
-            echo "changes_exist=false" >> $GITHUB_ENV
+            echo "changes_exist=false" >> "$GITHUB_ENV"
           else
             echo "Unpushed commits found."
-            echo "changes_exist=true" >> $GITHUB_ENV
+            echo "changes_exist=true" >> "$GITHUB_ENV"
           fi
 
       - name: push changes if they exist
@@ -47,8 +49,8 @@ jobs:
       - name: create release on new tag if new changes exist
         if: env.changes_exist == 'true'
         run: |
-          TAG_NAME=$(git describe --tags $(git rev-list --tags --max-count=1))
-          echo $TAG_NAME
+          TAG_NAME="$(git describe --tags "$(git rev-list --tags --max-count=1)")"
+          echo "$TAG_NAME"
           gh release create "$TAG_NAME" \
             --title "$TAG_NAME" \
             --notes "See: https://github.com/astral-sh/ruff/releases/tag/${TAG_NAME/v}" \

.gitignore

@@ -1,3 +1,5 @@
 __pycache__
 *.pyc
 .venv
+*.egg-info/
+.coverage

.markdownlint.yaml

@@ -0,0 +1,33 @@
+# Aligns with the main ruff repo markdownlint configuration.
+
+# default to true for all rules
+default: true
+
+# MD007/unordered-list-indent
+MD007:
+  indent: 4
+
+# MD033/no-inline-html
+MD033: false
+
+# MD041/first-line-h1
+MD041: false
+
+# MD013/line-length
+MD013: false
+
+# MD014/commands-show-output
+MD014: false
+
+# MD024/no-duplicate-heading
+MD024:
+  # Allow when nested under different parents e.g. CHANGELOG.md
+  siblings_only: true
+
+# MD046/code-block-style
+#
+# Ignore this because it conflicts with the code block style used in content
+# tabs of mkdocs-material which is to add a blank line after the content title.
+#
+# Ref: https://github.com/astral-sh/ruff/pull/15011#issuecomment-2544790854
+MD046: false

.pre-commit-config.yaml

@@ -0,0 +1,109 @@
+# # All hooks in this repo align with the main ruff repo unless otherwise noted.
+repos:
+  - repo: meta
+    hooks:
+      # Not in the main ruff repo but useful for checking that the current hooks are relevant
+      - id: check-hooks-apply
+      - id: check-useless-excludes
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      # The following hooks are not in the main ruff repo but are useful to checking files are formatted consistently
+      - id: check-case-conflict
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.23
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/executablebooks/mdformat
+    rev: 0.7.21
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          # Additional dependencies added to align with the main ruff repo even though mkdocs is not currently used
+          - mdformat-mkdocs==4.0.0
+          - mdformat-footnote==0.1.1
+
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.43.0
+    hooks:
+      - id: markdownlint-fix
+
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.19.1
+    hooks:
+      - id: blacken-docs
+        args: ["--pyi", "--line-length", "130"]
+        additional_dependencies:
+          - black==24.10.0
+        exclude: tests/test_ruff_format_docs.py
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.28.4
+    hooks:
+      - id: typos
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.13.0
+    hooks:
+      - id: mypy
+        args: [--config-file, pyproject.toml]
+        additional_dependencies:
+          - pytest==8.3.3
+          - urllib3==2.0.5
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        additional_dependencies:
+          - flake8-clean-block==0.1.2
+        args: ["--ignore=E,F,W,C90"]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  # Prettier
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.4.2
+    hooks:
+      - id: prettier
+        types: [yaml]
+
+  # zizmor detects security vulnerabilities in GitHub Actions workflows.
+  - repo: https://github.com/woodruffw/zizmor-pre-commit
+    rev: v0.10.0
+    hooks:
+      - id: zizmor
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.30.0
+    hooks:
+      - id: check-github-workflows
+
+  # `actionlint` hook, for verifying correct syntax in GitHub Actions workflows.
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.4
+    hooks:
+      - id: actionlint
+        stages:
+          # This hook is disabled by default, since it's quite slow.
+          # To run all hooks *including* this hook, use `uvx pre-commit run -a --hook-stage=manual`.
+          # To run *just* this hook, use `uvx pre-commit run -a actionlint --hook-stage=manual`.
+          - manual
+        args:
+          - "-ignore=SC2129" # ignorable stylistic lint from shellcheck
+          - "-ignore=SC2016" # another shellcheck lint: seems to have false positives?
+        additional_dependencies:
+          # actionlint has a shellcheck integration which extracts shell scripts in `run:` steps from GitHub Actions
+          # and checks these with shellcheck. This is arguably its most useful feature,
+          # but the integration only works if shellcheck is installed
+          - "github.com/wasilibs/go-shellcheck/cmd/[email protected]"

.pre-commit-hooks.yaml

@@ -19,3 +19,14 @@
   require_serial: true
   additional_dependencies: []
   minimum_pre_commit_version: "2.9.2"
+
+- id: ruff-format-docs
+  name: ruff-format-docs
+  description: Run the Ruff formatter on python code blocks in documentation files
+  entry: ruff-format-docs
+  language: python
+  types_or: [rst, markdown, python, tex]
+  args: []
+  require_serial: true
+  additional_dependencies: []
+  minimum_pre_commit_version: "2.9.2"