Skip to content

Exclude *.md files from formatting and linting - #2068

Merged
KatieB5 merged 1 commit into
mainfrom
KatieB5/exclude-markdown-files-from-ruff-formatting
Sep 23, 2026
Merged

KatieB5 merged 1 commit into
mainfrom
KatieB5/exclude-markdown-files-from-ruff-formatting

Conversation

@KatieB5

@KatieB5 KatieB5 commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Python embedded in Markdown is now automatically picked up by Ruff. 15c48a3 added a just check workflow in CI. We want this to run for PRs merging into main, but don't want researchers who contribute directly to the documentation to encounter failing checks due to formatting or linting of Python snippets in Markdown (discussion in Slack thread).

This PR excludes *.md files from Ruff formatting and linting.

Local testing

Introduce a formatting error in a .py file, and a python snippet in a .md file:

(.venv) $ just check
/home/katie/bin/just _compile requirements.prod.in requirements.prod.txt 
/home/katie/bin/just _compile requirements.dev.in requirements.dev.txt 
$BIN/ruff format --check .
unformatted: File would be reformatted
   --> docs/case-control-studies.md:183:6
    |
182 |         "index_date": datetime.date,
    -     }
183 +     },
184 | )
    |

invalid-syntax: Unexpected indentation
  --> hooks/ehrql_branch.py:17:1
   |
15 |     """
16 | ehrql_branch = config["extra"]["ehrql_branch"]
17 |     if ehrql_branch == "main":
   | ^^^^
18 |         return config
19 |     ehrql_nav_index, ehrql_nav_section = next(
   |

1 file would be reformatted, 109 files already formatted
error: recipe `format` failed on line 112 with exit code 2

Update pyproject.toml to add the exclude-extend setting and exclude markdown files.

(.venv) $ just check
/home/katie/bin/just _compile requirements.prod.in requirements.prod.txt 
/home/katie/bin/just _compile requirements.dev.in requirements.dev.txt 
$BIN/ruff format --check .
invalid-syntax: Unexpected indentation
  --> hooks/ehrql_branch.py:17:1
   |
15 |     """
16 | ehrql_branch = config["extra"]["ehrql_branch"]
17 |     if ehrql_branch == "main":
   | ^^^^
18 |         return config
19 |     ehrql_nav_index, ehrql_nav_section = next(
   |

6 files already formatted
error: recipe `format` failed on line 112 with exit code 2

Only the .py formatting error is picked up.

NOTE: Once this PR is merged, branch protection rules will need to be updated in the docs repo Settings, to enforce the new just check CI workflow to run for PRs to merge into main.

TO DO:

Python embedded in Markdown is now automatically picked up by Ruff.
15c48a3 added a just check workflow in CI. We want this to run for
PRs merging into main, but don't want researchers who contribute directly to
the documentation to encounter failing checks due to formatting or
linting of Python snippets in Markdown.

Add `extend-exclude = ["*.md"]` to `pyproject.toml`, as recommended in
the Ruff docs (https://docs.astral.sh/ruff/formatter/#markdown-code-formatting).

Also remove the `<!-- fmt:off --> / <!-- fmt:on -->` comments
introduced in 70ff69a. These were only needed to suppress Ruff's
Markdown formatting and are redundant now that Markdown files are
excluded.

Once this PR is merged, branch protection rules will need to be updated
in the docs repo Settings, to enforce the new CI workflow.
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying opensafely-docs with  Cloudflare Pages  Cloudflare Pages

Latest commit: b05b307
Status: ✅  Deploy successful!
Preview URL: https://98b149fe.opensafely-docs.pages.dev
Branch Preview URL: https://katieb5-exclude-markdown-fil.opensafely-docs.pages.dev

View logs

@KatieB5
KatieB5 marked this pull request as ready for review September 23, 2026 08:28
@KatieB5
KatieB5 merged commit 5b28239 into main Sep 23, 2026
4 checks passed
@KatieB5
KatieB5 deleted the KatieB5/exclude-markdown-files-from-ruff-formatting branch September 23, 2026 12:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants