Skip to content

Enforce README syncing with docs dir via Jinja2 template and hook#1730

Merged
nathanjmcdougall merged 5 commits intomainfrom
copilot/enforce-readme-syncing-with-docs-dir
Apr 1, 2026
Merged

Enforce README syncing with docs dir via Jinja2 template and hook#1730
nathanjmcdougall merged 5 commits intomainfrom
copilot/enforce-readme-syncing-with-docs-dir

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 1, 2026

README.md is manually assembled from several docs/ files with transformations (header demotion, link absolutization, TIP callout wrapping). This was only validated by a test, not enforced at commit time.

Adds a Jinja2 template + pre-commit hook that auto-generates README.md from doc sources, replacing the manual sync workflow.

  • docs/README.md.jinja — Template with {{ include_doc(...) }} calls that pull in content from docs/ with per-include transformations
  • hooks/fix-readme.py — Fixer hook (exit 1 on modification, following existing export hook pattern). _include_doc() supports skip_lines, demote_headers, replacements dict, and tip_text callout wrapping
  • .pre-commit-config.yaml — Registers fix-readme at priority 1 (after markdownlint/prettier process doc files at priority 0)
  • Removed tests/docs/test_readme.py — The test_assemble_readme_from_docs test is now redundant since the hook enforces the same invariant at commit time
  • Updated .github/workflows/ci.yml — Added docs/** and **/*.md to paths-ignore (for both push and pull_request), matching the patterns already used by codecov, codspeed, codeql, and zizmor workflows. The static-checks.yml workflow intentionally has no paths-ignore and continues to run on all changes.

Template usage in docs/README.md.jinja:

{{ include_doc("docs/index.md", skip_lines=2, demote_headers=false) }}

{{ include_doc("docs/cli/overview.md", replacements={"](reference.md#": "](https://usethis.readthedocs.io/en/stable/cli/reference#"}) }}

{{ include_doc("docs/about/similar-projects.md", replacements={...}, tip_text="You can still use usethis") }}

Jinja2 is already a dev dependency.

Copilot AI and others added 2 commits April 1, 2026 12:38
Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/3d47e812-7793-44fb-8c22-6c925345f5ff

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/3d47e812-7793-44fb-8c22-6c925345f5ff

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Copilot AI changed the title [WIP] Add README syncing with docs directory via hook Enforce README syncing with docs dir via Jinja2 template and hook Apr 1, 2026
Copilot AI requested a review from nathanjmcdougall April 1, 2026 12:43
@nathanjmcdougall nathanjmcdougall marked this pull request as ready for review April 1, 2026 12:46
Comment thread docs/README.md.jinja
@codecov
Copy link
Copy Markdown

codecov bot commented Apr 1, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/181a66fb-f111-47de-8f55-e47b6593475b

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
@codspeed-hq
Copy link
Copy Markdown

codspeed-hq bot commented Apr 1, 2026

Merging this PR will not alter performance

✅ 2 untouched benchmarks


Comparing copilot/enforce-readme-syncing-with-docs-dir (da1a1a1) with main (bbd11fe)

Open in CodSpeed

@nathanjmcdougall
Copy link
Copy Markdown
Collaborator

@copilot

We should deprecate the test_assemble_readme_from_docs test, which basically encodes the logic we want out of the hook.

Then, we can configure the GitHub actions workflows to skip any changes to .md files, anywhere, and all changes in the docs dir. The only exception would be the static checks workflow - that would still run.

… to CI

Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/8049bb38-5414-4c85-975a-effbbe1cfe80

Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
Copy link
Copy Markdown
Contributor Author

Copilot AI commented Apr 1, 2026

@copilot

We should deprecate the test_assemble_readme_from_docs test, which basically encodes the logic we want out of the hook.
...

Done in da1a1a1:

  1. Removed tests/docs/test_readme.py entirely — the fix-readme hook now enforces the same invariant at commit time.
  2. Updated ci.yml to add docs/** and **/*.md to paths-ignore (for both push and pull_request), replacing the previous specific entries like CHANGELOG.md, AGENTS.md, .agents/**/*.md, and docs/**/*.txt which are all subsumed by the broader patterns. The static-checks.yml workflow is left unchanged — it continues to run on all paths.

@nathanjmcdougall nathanjmcdougall merged commit f513846 into main Apr 1, 2026
20 checks passed
@nathanjmcdougall nathanjmcdougall deleted the copilot/enforce-readme-syncing-with-docs-dir branch April 1, 2026 13:21
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.

Enforce README syncing with docs dir via hook

2 participants