diff --git a/template/AGENTS.md.jinja b/template/AGENTS.md.jinja new file mode 100644 index 0000000..260f49d --- /dev/null +++ b/template/AGENTS.md.jinja @@ -0,0 +1,77 @@ +# {{ project_name }} agent guide + +## Project overview + +- Distribution: `{{ distribution_name }}` +- Import package: `{{ package_name }}` +- Source directory: `src/{{ package_name }}/` +- Tests: `tests/` +- Repository: {{ repository_url }} + +{{ project_description }} + +## Working conventions + +Read and follow [STYLE.md](STYLE.md) before changing Python code or tests. +`pyproject.toml` is the source of truth for dependency groups, Ruff, mypy, +pytest, and coverage configuration. + +Keep changes focused, preserve public behavior unless the task intentionally +changes it, and add or update tests for behavior changes. + +## Development notes + +Use `devnotes/` to record concise, task-specific context during development. +Read [devnotes/example.md](devnotes/example.md) before starting a note, and +replace it with notes that capture decisions, validation results, and useful +follow-up work. + +## Validation + +{% if tasks == "tox" -%} +Use tox to run the generated automation: + +```console +uvx tox -m checks +uvx tox -m tests +``` +{%- elif tasks == "nox" %} +Use the generated Nox script to run automation: + +```console +uv run noxfile.py -s lint +uv run noxfile.py -s typecheck +uv run noxfile.py -s tests +``` +{%- else %} +Run the appropriate dependency group directly: + +```console +uv run --group lint pre-commit run --all-files +uv run --group type mypy src tests +uv run --group test pytest +``` +{%- endif %} +{%- if docs %} + +## Documentation + +Documentation lives in `docs/`. Build it with the applicable command below +before submitting documentation changes. +{%- if tasks == "tox" %} + +```console +uvx tox -e docs +``` +{%- elif tasks == "nox" %} + +```console +uv run noxfile.py -s docs +``` +{%- else %} + +```console +uv run --group docs {{ "mkdocs" if docs == "mkdocs" else "zensical" }} build --strict +``` +{%- endif %} +{%- endif %} diff --git a/template/STYLE.md b/template/STYLE.md new file mode 100644 index 0000000..557282d --- /dev/null +++ b/template/STYLE.md @@ -0,0 +1,29 @@ +# Python style guide + +Follow the configured Ruff rules in `pyproject.toml`. This document specifies +the project conventions that complement those rules. + +## Code and documentation + +- Use double quotes for all strings. +- Add type hints to all code. +- Use NumPy-style docstrings only. +- Thoroughly document public classes and methods. +- Private classes, methods, globals, and similar implementation details may + have brief documentation or none when their purpose is clear from context. +- Make errors and warnings concise and informative. Avoid multi-sentence + messages unless a single sentence would sacrifice clarity. + +## Design + +- Prefer legible, concise, minimal code. +- Avoid unnecessary abstractions and large collections of private helpers. +- Inline very short helpers. +- Do not extract simple logic merely because it appears once or twice. Keep + such logic at its call sites when it is likely to need independent changes. + +## Tests + +- Keep test suites DRY and concise. +- Use pytest fixtures, parametrization, and mocks where they make tests more + readable or remove duplication. diff --git a/template/devnotes/example.md b/template/devnotes/example.md new file mode 100644 index 0000000..6b00ad0 --- /dev/null +++ b/template/devnotes/example.md @@ -0,0 +1,17 @@ +# Example development note + +## Goal + +Briefly state the task or investigation. + +## Decisions and findings + +- Record relevant constraints, decisions, and observations as work progresses. + +## Validation + +- List the checks run and their outcomes. + +## Follow-up + +- Note remaining work, risks, or questions for the next contributor. diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index e96a14e..1138b2b 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -140,7 +140,7 @@ lint.per-file-ignores."tests/**" = [ lint.isort.required-imports = [ "from __future__ import annotations", ] -lint.pydocstyle.convention = "google" +lint.pydocstyle.convention = "numpy" lint.future-annotations = true [tool.codespell]