feat: implement python-based repository bootstrapping and modernize documentation by markurtz · Pull Request #6 · markurtz/template-python

markurtz · 2026-05-14T19:39:49Z

Description

This PR introduces a comprehensive overhaul to the repository bootstrapping process and modernizes the project's documentation infrastructure. It replaces the previous shell-based bootstrap script with a robust, type-safe Python implementation (scripts/bootstrap.py) that includes conditional toggles for project features, such as defaulting PyPI publishing workflows to an inactive state. Additionally, this PR addresses multiple documentation formatting issues, integrates coverage reporting, and resolves issues with the MkDocs version switcher.

Key changes include:

Bootstrap Process Improvements: Replaced scripts/bootstrap.sh with a comprehensive, fully tested Python script (scripts/bootstrap.py). Encapsulated bootstrap logic within a BootstrapConfig class, adding conditional toggling for PyPI publishing and automated regex-based template placeholder replacement.
Documentation Overhaul: Fixed the mike version dropdown, modernized documentation layout by migrating to native MkDocs Material attributes, updated links to be absolute, and relocated gen_ref_pages.py to the docs/ directory. Successfully integrated coverage reports into the documentation pipeline.
Project Structure & CI: Renamed the default source directory from project_name to template_python to be functional out-of-the-box. Updated GitHub Action configurations and resolved pre-commit CI pipeline issues.
Comprehensive Testing: Added full end-to-end and unit test coverage for the new Python bootstrapping infrastructure.

Type of Change

🐛 Bug fix (non-breaking change which fixes an issue)
✨ New feature (non-breaking change which adds functionality)
💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
📝 Documentation update (changes to README.md, SUPPORT.md, docstrings, etc.)
🛠️ Maintenance/Refactoring (non-breaking change that improves code structure or quality)

Test Plan

Verified uv run scripts/bootstrap.py locally to confirm all placeholder templates are appropriately populated.
Validated that optional features like PyPI GitHub Actions are accurately toggled/disabled by default.
Served the documentation locally via hatch run docs:serve to confirm proper rendering of grid card layouts, the version switcher, and code coverage integration.
Ran the full test suite using hatch run test:all to verify that all new bootstrapping logic unit and end-to-end tests successfully pass without environmental side-effects.

Related Issues

Screenshots / Visuals (if applicable)

Use of AI

Includes AI-assisted code completion
Includes code generated by an AI application
Includes AI-generated tests

Checklist

Important

Please review and complete this checklist before submitting your PR. This helps our maintainers process your contribution faster and ensures it meets the quality standards of template-python.

"I certify that all code in this PR is my own, except as noted below."
I have read the CONTRIBUTING.md guide.
My code follows the established style guidelines of template-python.
I have performed a self-review of my own code.
I have commented my code, particularly in hard-to-understand areas.
I have made corresponding changes to the documentation.
My changes generate no new warnings or errors.
I have added tests that prove my fix is effective or that my feature works.
New and existing unit tests pass locally with my changes.

…ng included in docs, and misc incorrect docs and incorrect references for the org and project due to intended replacement

…ject to ensure it is easy and foolproof to do and generates a usable repo while also ensuring template-python is a usable repo on its own

github-actions · 2026-05-14T19:41:34Z

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

Copilot

Pull request overview

This PR replaces the shell bootstrap flow with a Python-based bootstrapper, renames the default package to template_python / template-python, and refreshes documentation, tests, and CI/doc workflows around the template repository.

Changes:

Adds scripts/bootstrap.py plus unit and E2E tests for repository bootstrapping.
Updates package/module references from project_name to template_python / template-python.
Modernizes docs, MkDocs API generation, coverage docs integration, and workflow dependencies.

Reviewed changes

Copilot reviewed 57 out of 60 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
`scripts/bootstrap.py`	Adds Python bootstrap implementation and feature toggles.
`scripts/bootstrap.sh`	Removes old shell bootstrapper.
`scripts/README.md`	Documents new bootstrap script usage.
`pyproject.toml`	Renames package, updates deps, docs deps, scripts, tooling config.
`uv.lock`	Updates lockfile for renamed package and new dependencies.
`src/template_python/*`	Updates package docs/imports/env prefixes and CLI entrypoint.
`tests/**`	Updates imports/expectations and adds bootstrap tests.
`docs/**`	Updates documentation content and generated API reference setup.
`.github/workflows/*`	Adjusts docs dependencies and disables PyPI publish steps by default.
`.github/ISSUE_TEMPLATE/*`	Updates template repository references.
`.github/PULL_REQUEST_TEMPLATE.md`	Updates PR template wording/references.
`README.md`	Updates bootstrap guidance and project references.
`AGENTS.md`, `CONTRIBUTING.md`, `DEVELOPING.md`, `SECURITY.md`, `SUPPORT.md`, `CODE_OF_CONDUCT.md`, `NOTICE`, `CITATION.cff`	Updates repository metadata and documentation references.
`Dockerfile`, `docker-compose.yml`	Updates container/module references.
`examples/**`	Updates example imports and docs.
`.env.example`, `.editorconfig`, `.gitignore`	Updates default names and generated-file paths.
`llms.txt`, `llms-full.txt`	Updates LLM-facing documentation references.
`mkdocs.yml`	Adds generated API docs plugins and updated site metadata.

Comments suppressed due to low confidence (1)

src/template_python/logging.py:6

The updated module docstring is grammatically incomplete: “It handles dynamic OpenTelemetry formatting, across...” is missing the object that was removed from the sentence.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

github-actions · 2026-05-14T19:46:27Z

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

Agent-Logs-Url: https://github.com/markurtz/template-python/sessions/956319d3-b149-462b-86f8-f3ac0d6bf3c0 Co-authored-by: markurtz <12499095+markurtz@users.noreply.github.com>

github-actions · 2026-05-14T19:58:42Z

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Mark Kurtz <mark.j.kurtz@gmail.com>

github-actions · 2026-05-14T20:00:43Z

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

- Replace {{year}} placeholder instead of all "2026" literals to avoid corrupting unrelated content - Add Path.cwd() support to E2E test MockPath class - Add noqa: E402 to suppress import-after-sys.path.insert lint errors in test files Agent-Logs-Url: https://github.com/markurtz/template-python/sessions/cffd9703-e40f-459e-9641-1018b1db6dd8 Co-authored-by: markurtz <12499095+markurtz@users.noreply.github.com>

github-actions · 2026-05-14T20:01:27Z

CI Development Pipeline Status

❌ Pipeline: Failed or was cancelled. Check logs

github-actions · 2026-05-14T20:02:35Z

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details

- Fix example template README to use correct module name (template_python instead of template-python) - Update llms-full.txt to reference bootstrap.py script instead of manual find-and-replace - Fix BootstrapConfig.create() to include default global_blacklist for programmatic usage Agent-Logs-Url: https://github.com/markurtz/template-python/sessions/cb6d7229-712f-41d2-bb7e-c18a17906cac Co-authored-by: markurtz <12499095+markurtz@users.noreply.github.com>

github-actions · 2026-05-14T20:07:03Z

CI Development Pipeline Status

✅ Pipeline: Completed successfully. View Run Details

markurtz added 4 commits May 13, 2026 22:21

Fix issues around docs versions not showing, coverage reports not bei…

c052877

…ng included in docs, and misc incorrect docs and incorrect references for the org and project due to intended replacement

Fixes around documentation and general fixes for boostrapping the pro…

2466aca

…ject to ensure it is easy and foolproof to do and generates a usable repo while also ensuring template-python is a usable repo on its own

fixed tests and formatting

719bed4

Update docs for the new boostrap.py

f34d287

markurtz requested a review from Copilot May 14, 2026 19:39

markurtz self-assigned this May 14, 2026

Copilot started reviewing on behalf of markurtz May 14, 2026 19:40 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

Copilot started work on behalf of markurtz May 14, 2026 19:51 View session

Copilot AI and others added 3 commits May 14, 2026 19:55

fix: support directory-qualified glob matching in bootstrap

43219de

Agent-Logs-Url: https://github.com/markurtz/template-python/sessions/956319d3-b149-462b-86f8-f3ac0d6bf3c0 Co-authored-by: markurtz <12499095+markurtz@users.noreply.github.com>

test: cover non-matching bootstrap glob cases

118b1f5

Agent-Logs-Url: https://github.com/markurtz/template-python/sessions/956319d3-b149-462b-86f8-f3ac0d6bf3c0 Co-authored-by: markurtz <12499095+markurtz@users.noreply.github.com>

fix(lint): correct module name in ruff configuration

4c7d686

Copilot finished work on behalf of markurtz May 14, 2026 19:58

Copilot started work on behalf of markurtz May 14, 2026 19:58 View session

markurtz and others added 3 commits May 14, 2026 15:59

Potential fix for pull request finding

b6612d3

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Mark Kurtz <mark.j.kurtz@gmail.com>

Potential fix for pull request finding

f76e7b6

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Mark Kurtz <mark.j.kurtz@gmail.com>

Potential fix for pull request finding

66aad29

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Mark Kurtz <mark.j.kurtz@gmail.com>

Copilot finished work on behalf of markurtz May 14, 2026 20:03

Copilot started work on behalf of markurtz May 14, 2026 20:03 View session

markurtz and others added 2 commits May 14, 2026 16:05

Fixes for year replacement tag

da4764b

Copilot finished work on behalf of markurtz May 14, 2026 20:08

markurtz merged commit 4206e1a into main May 14, 2026
13 checks passed

markurtz deleted the feature/usage-upgrades branch May 14, 2026 20:16

Conversation

markurtz commented May 14, 2026

Description

Type of Change

Test Plan

Related Issues

Screenshots / Visuals (if applicable)

Use of AI

Checklist

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

github-actions Bot commented May 14, 2026

CI Development Pipeline Status

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants