Learning Resources¶
Curated links to documentation, tutorials, and references for the tools and patterns used in this project. Organized by topic for quick lookup.
Python Packaging & Project Structure¶
| Resource | Description |
|---|---|
| Python Packaging User Guide | Official guide — covers pyproject.toml, src/ layout, builds, and publishing |
| PEP 621 — Project metadata | The standard for declaring metadata in pyproject.toml |
| PEP 517 — Build system interface | How build backends (Hatchling, setuptools) work under the hood |
| src layout vs flat layout | Official comparison — why we chose src/ (ADR 001) |
| Hatch documentation | Project manager used for environments, builds, and scripts |
| Hatchling documentation | Build backend configuration |
Testing¶
| Resource | Description |
|---|---|
| pytest documentation | Test framework — fixtures, parametrize, markers, plugins |
| pytest-cov | Coverage plugin for pytest |
| Effective Python Testing with pytest (Real Python) | Practical tutorial covering fixtures, marks, and parametrize |
| Testing Best Practices (The Hitchhiker's Guide) | General Python testing guidance |
Linting, Formatting & Type Checking¶
| Resource | Description |
|---|---|
| Ruff documentation | Linter + formatter — rules reference, configuration |
| Ruff rule index | Searchable index of all lint rules by code |
| mypy documentation | Static type checker — configuration, error codes, stubs |
| mypy cheat sheet | Quick reference for type annotations |
| typing module docs | Standard library typing reference |
Pre-commit Hooks¶
| Resource | Description |
|---|---|
| pre-commit documentation | Hook framework — installation, configuration, creating hooks |
| pre-commit hook directory | Searchable directory of available hooks |
| Supported hooks in this project | Full inventory of hooks used here (ADR 008) |
GitHub Actions & CI/CD¶
| Resource | Description |
|---|---|
| GitHub Actions documentation | Official docs — workflows, syntax, runners, expressions |
| Workflow syntax reference | Complete YAML syntax for workflow files |
| GitHub Actions expressions | ${{ }} expression syntax, contexts, functions |
| Security hardening for Actions | Best practices — permissions, SHA pinning, secrets |
| actionlint | Workflow linter — catches errors before pushing |
| act | Run GitHub Actions locally for faster iteration |
Security Tools¶
| Resource | Description |
|---|---|
| Bandit documentation | Python security linter — issue types, configuration |
| pip-audit | Vulnerability scanning for Python dependencies |
| gitleaks | Secret detection in git repositories |
| Trivy | Container and dependency vulnerability scanner |
| OpenSSF Scorecard | Supply-chain security scoring |
| OWASP Cheat Sheet Series | Application security cheat sheets (OWASP) |
Documentation (MkDocs)¶
| Resource | Description |
|---|---|
| MkDocs documentation | Static site generator for project docs |
| Material for MkDocs | Theme used in this project — features, customization |
| mkdocstrings | Auto-generate API docs from Python docstrings |
| Google Python Style Guide — Docstrings | Docstring convention used in this project |
Containers¶
| Resource | Description |
|---|---|
| Dockerfile reference | Syntax reference for Containerfile / Dockerfile |
| Multi-stage builds | Pattern used in our Containerfile for minimal images |
| Podman documentation | Daemonless container engine (alternative to Docker) |
| Dev Containers specification | Standard for development containers (VS Code / Codespaces) |
Git & Conventional Commits¶
| Resource | Description |
|---|---|
| Pro Git book (free) | The definitive Git book — covers fundamentals through advanced topics |
| Git documentation | Official reference — man pages, videos, cheat sheet |
| Learn Git Branching | Interactive visual tutorial for learning Git branching |
| Oh Shit, Git!?! | Plain-English fixes for common Git mistakes |
| Git flight rules | FAQ-style guide — "I did X, how do I fix it?" |
| GitHub Git cheat sheet | One-page PDF reference for common commands |
| Atlassian Git tutorials | Well-illustrated guides on branching, merging, rebasing |
| Conventional Commits | Commit message convention used in this project |
| commitizen | CLI tool for authoring conventional commits |
| release-please | Automated release management from conventional commits |
Architecture Decision Records¶
| Resource | Description |
|---|---|
| ADR overview (adr.github.io) | What ADRs are and why they matter |
| Michael Nygard's ADR article | Original blog post that popularized ADRs |
| MADR template | Markdown ADR template (similar to ours) |
General Python¶
| Resource | Description |
|---|---|
| Python documentation | Official language and stdlib reference |
| Real Python | High-quality tutorials and guides |
| The Hitchhiker's Guide to Python | Best practices for Python development |
| PEP 8 — Style Guide | The foundational Python style guide (Ruff enforces most of this) |
| Python Type Hints cheat sheet | Quick reference for common type patterns |
| Python 3 Module of the Week | In-depth stdlib module walkthroughs |
| Fluent Python (book) | Advanced Python — data models, concurrency, metaprogramming |
Project Dependencies (Dev & Test)¶
Every tool declared in pyproject.toml [project.optional-dependencies]:
| Tool | Docs | Description |
|---|---|---|
| pytest | docs.pytest.org | Testing framework |
| pytest-cov | pytest-cov.readthedocs.io | Coverage plugin for pytest |
| Ruff | docs.astral.sh/ruff | Linter + formatter |
| mypy | mypy.readthedocs.io | Static type checker |
| pre-commit | pre-commit.com | Git hooks framework |
| Bandit | bandit.readthedocs.io | Security linter for Python |
| commitizen | commitizen-tools.github.io | Conventional commit helper |
| deptry | deptry.com | Dependency hygiene checker |
| pipdeptree | github.com/tox-dev/pipdeptree | Dependency tree visualizer |
| MkDocs | mkdocs.org | Documentation site generator |
| Material for MkDocs | squidfunk.github.io/mkdocs-material | MkDocs theme |
| pymdown-extensions | facelessuser.github.io/pymdown-extensions | Markdown extensions (tabbed, highlight, superfences) |
| mkdocstrings | mkdocstrings.github.io | Auto-generate API docs from docstrings |
Configuration File Formats¶
| Resource | Description |
|---|---|
| TOML specification | Config file format used by pyproject.toml |
| YAML specification | Config format used by workflows, mkdocs.yml, pre-commit |
| YAML multiline strings | Interactive guide to YAML's confusing string styles |
| JSON Schema | Used for labels/*.json, GitHub issue templates |
| Cron expression guide | Interactive helper for GitHub Actions schedule cron syntax |
GitHub Platform¶
| Resource | Description |
|---|---|
| GitHub Docs | Official platform documentation |
| Branch protection rules | How to configure required checks |
| Repository variables | Variables and secrets for Actions (used by repository guards) |
| Dependabot documentation | Automated dependency updates |
| GitHub Pages | Hosting docs from the repo (used by docs-deploy workflow) |
| GitHub Codespaces | Cloud dev environments (pairs with .devcontainer/) |
| GitHub CLI (gh) | Command-line tool for GitHub — PRs, issues, releases |
Task Runner¶
| Resource | Description |
|---|---|
| Taskfile documentation | Task runner used for task test, task lint, etc. |
| Taskfile schema reference | YAML schema for Taskfile.yml |
Software Supply Chain & SBOMs¶
| Resource | Description |
|---|---|
| SPDX specification | Software Package Data Exchange — SBOM format |
| CycloneDX specification | Alternative SBOM format (also generated by this project) |
| OpenSSF best practices | Open Source Security Foundation guidelines |
| SLSA framework | Supply-chain Levels for Software Artifacts |
Markdown & Formatting¶
| Resource | Description |
|---|---|
| Prettier documentation | Code formatter used for Markdown files in this project |
| markdownlint rules | Rule reference for markdownlint-cli2 |
| GitHub Flavored Markdown | GitHub's Markdown spec — tables, task lists, autolinks |
| CommonMark specification | The foundational Markdown standard |
AI Coding Assistants¶
| Resource | Description |
|---|---|
| GitHub Copilot custom instructions | How .github/copilot-instructions.md works |
| Copilot chat documentation | Using Copilot in VS Code |
| Cursor Rules | Similar context files for the Cursor editor |
Modern Python Tooling¶
| Resource | Description |
|---|---|
| uv documentation | Ultra-fast Python package installer and resolver (Astral) |
| Rye documentation | Experimental Python project manager (Astral, merging into uv) |
| Scientific Python Development Guide | Modern packaging guide for scientific Python |
| Hypermodern Python | Blog series on modern Python project setup |
How to Use This Page¶
- New to the project? Start with the Python Packaging, Git, and Testing sections
- Setting up CI? GitHub Actions, GitHub Platform, and Security Tools sections
- Writing docs? MkDocs section and the Google docstring guide
- Configuring tools? Configuration File Formats section for TOML/YAML reference
- Looking for a tool's docs? Project Dependencies table links every dev tool
- Making an architectural decision? ADR section for the template and process
- Using AI assistants? AI Coding Assistants section +
copilot-instructions.md
This is a living document — add links as you discover useful resources and remove ones that go stale.
For self-written references and cheat sheets (e.g., Git commands), see resources_written.md.