From 374bc93c04710bc2f21cd18bf19aba832b6b6e3e Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 18:25:17 +0200 Subject: [PATCH 01/15] fix commitizen pre commit hook --- {{cookiecutter.project_slug}}/.pre-commit-config.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml index 09eaf78..2fb7030 100644 --- a/{{cookiecutter.project_slug}}/.pre-commit-config.yaml +++ b/{{cookiecutter.project_slug}}/.pre-commit-config.yaml @@ -11,8 +11,9 @@ repos: hooks: - id: commitizen name: commitizen - entry: commitizen - language: system + entry: cz check + args: [--allow-abort, --commit-msg-file] + language: python stages: [commit-msg] - repo: local hooks: From ab00cb2252dba4d36bbb499b4ef5b3bc4940706a Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 18:37:02 +0200 Subject: [PATCH 02/15] fix github workflows --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 2 +- {{cookiecutter.project_slug}}/.github/workflows/test.yml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index e065153..f904cbb 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -43,7 +43,7 @@ jobs: run: python docs/gen_api_docs.py - name: Build documentation - run: mkdocs build + run: uv run mkdocs build - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/{{cookiecutter.project_slug}}/.github/workflows/test.yml b/{{cookiecutter.project_slug}}/.github/workflows/test.yml index a96cff3..a741956 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/test.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/test.yml @@ -29,7 +29,7 @@ jobs: python-version-file: "pyproject.toml" - name: Install the project - run: uv sync --all-extras --dev --group test + run: uv sync --all-extras --dev - name: Run tests run: uv run pytest tests -sv From 1b4191453faae9217b58b1662d8f8bc6865c1c1c Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 18:39:46 +0200 Subject: [PATCH 03/15] update readme template --- {{cookiecutter.project_slug}}/README.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index aac81fd..14e2670 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -3,22 +3,5 @@ {{ cookiecutter.project_short_description }} {% if cookiecutter.use_mkdocs == 'y' %} -## Documentation - -This project uses MkDocs for documentation. To build and view the documentation locally: - -```bash -# Install documentation dependencies -uv sync --group docs - -# Generate API documentation -python docs/gen_api_docs.py - -# Serve documentation locally -mkdocs serve -``` - -The documentation will be available at http://127.0.0.1:8000/ - -When you push to the main branch, the documentation will automatically be built and deployed to GitHub Pages. +[docs](https://{{cookiecutter.github_username}}.github.io/{{cookiecutter.project_slug}}) {% endif %} From 5499d4c04d8e2a6e76da3a09ddbd90ad6dbb9b06 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:26:27 +0200 Subject: [PATCH 04/15] add github templates --- .github/ISSUE_TEMPLATE/bug.md | 22 +++++++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 17 ++++++++++++ .github/ISSUE_TEMPLATE/question.md | 13 +++++++++ .github/PULL_REQUEST_TEMPLATE.md | 11 ++++++++ .github/SECURITY.md | 19 +++++++++++++ .../.github/ISSUE_TEMPLATE/bug.md | 27 +++++++++++++++++++ .../.github/ISSUE_TEMPLATE/feature_request.md | 17 ++++++++++++ .../.github/ISSUE_TEMPLATE/question.md | 15 +++++++++++ .../.github/PULL_REQUEST_TEMPLATE.md | 10 +++++++ .../.github/SECURITY.md | 19 +++++++++++++ .../.github/workflows/docs.yml | 3 --- 11 files changed, 170 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md create mode 100644 {{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/bug.md create mode 100644 {{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/feature_request.md create mode 100644 {{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md create mode 100644 {{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md create mode 100644 {{cookiecutter.project_slug}}/.github/SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..2d6e05d --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,22 @@ +--- +name: Bug +about: Create a bug report to help us improve +labels: bug +--- + +## Description + + +## Steps to reproduce + + +## Current behavior + + +## Desired behavior + + +## Environment diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..16a57f9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Feature Request +about: Suggest a new feature or change +labels: feature request +--- + +## Description + + +## Possible Solution + + +## Additional context + + +## Related Issue + diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..2ab2344 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,13 @@ +--- +name: Question +about: Ask a question about how to use the template +labels: question +--- + + + +## Question diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..215477b --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,11 @@ + + + +## Checklist + +* [ ] Add test cases to all the changes you introduce +* [ ] Update the documentation for the changes diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..a001a90 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +## Supported Versions + +We will endeavour to support: + +* The most recent minor release with bug fixes. +* The latest minor release from the last major version for 6 months after a new + major version is released with critical bug fixes. +* All versions if a security vulnerability is found provided: + * Upgrading to a later version is non-trivial. + * Sufficient people are using that version to make support worthwhile. + +## Reporting a Vulnerability + +If you find what you think might be a security vulnerability with the project, +please do not create an issue on github. Instead please email +adrianlattes@disroot.org. I'll reply to your email promptly and try to get a +patch out ASAP. diff --git a/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/bug.md b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/bug.md new file mode 100644 index 0000000..62f0e86 --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/bug.md @@ -0,0 +1,27 @@ +--- +name: Bug +about: Create a bug report to help us improve {{ cookiecutter.project_slug }} +labels: bug +--- + +## Description + + +## Steps to reproduce + + +## Current behavior + + +## Desired behavior + + +## Environment diff --git a/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/feature_request.md b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..5b02188 --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: Feature Request +about: Suggest a new feature or change to {{ cookiecutter.project_slug }} +labels: feature request +--- + +## Description + + +## Possible Solution + + +## Additional context + + +## Related Issue + diff --git a/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..2b682be --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,15 @@ +--- +name: Question +about: Ask a question about how to use {{ cookiecutter.project_slug }} +labels: question +--- + + + +## Question diff --git a/{{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md b/{{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..9ddb83b --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,10 @@ + + +## Checklist + +* [ ] Add test cases to all the changes you introduce +* [ ] Update the documentation for the changes diff --git a/{{cookiecutter.project_slug}}/.github/SECURITY.md b/{{cookiecutter.project_slug}}/.github/SECURITY.md new file mode 100644 index 0000000..418707f --- /dev/null +++ b/{{cookiecutter.project_slug}}/.github/SECURITY.md @@ -0,0 +1,19 @@ +# Security Policy + +## Supported Versions + +We will endeavour to support: + +* The most recent minor release with bug fixes. +* The latest minor release from the last major version for 6 months after a new + major version is released with critical bug fixes. +* All versions if a security vulnerability is found provided: + * Upgrading to a later version is non-trivial. + * Sufficient people are using that version to make support worthwhile. + +## Reporting a Vulnerability + +If you find what you think might be a security vulnerability with +{{ cookiecutter.project_slug }}, please do not create an issue on github. Instead please +email {{ cookiecutter.security_advisories_email }} I'll reply to your email promptly +and try to get a patch out ASAP. diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index f904cbb..84e9493 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -39,9 +39,6 @@ jobs: - name: Install the project with docs dependencies run: uv sync --all-extras --dev --group docs - - name: Generate API documentation - run: python docs/gen_api_docs.py - - name: Build documentation run: uv run mkdocs build From 3d4db0aa3b5a3048b772852809de11c32ae08219 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:26:49 +0200 Subject: [PATCH 05/15] improve default docs --- .../docs/api/index.md | 2 - .../docs/contributing.md | 168 ++++++++++++++---- .../docs/gen_api_docs.py | 69 ------- {{cookiecutter.project_slug}}/docs/index.md | 2 - 4 files changed, 137 insertions(+), 104 deletions(-) delete mode 100644 {{cookiecutter.project_slug}}/docs/gen_api_docs.py diff --git a/{{cookiecutter.project_slug}}/docs/api/index.md b/{{cookiecutter.project_slug}}/docs/api/index.md index 65fdecc..a121eae 100644 --- a/{{cookiecutter.project_slug}}/docs/api/index.md +++ b/{{cookiecutter.project_slug}}/docs/api/index.md @@ -1,7 +1,5 @@ -{% if cookiecutter.use_mkdocs == 'y' %} # API Reference This section contains auto-generated API reference documentation. ::: {{ cookiecutter.project_slug }} -{% endif %} diff --git a/{{cookiecutter.project_slug}}/docs/contributing.md b/{{cookiecutter.project_slug}}/docs/contributing.md index fa3f47b..6659339 100644 --- a/{{cookiecutter.project_slug}}/docs/contributing.md +++ b/{{cookiecutter.project_slug}}/docs/contributing.md @@ -1,47 +1,153 @@ -{% if cookiecutter.use_mkdocs == 'y' %} -# Contributing +So you've started using `{{ cookiecutter.project_slug }}` and want to show your +gratitude to the project, depending on your programming skills there are +different ways to do so. -Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. +# I don't know how to program -## Development +There are several ways you can contribute: -To set up this project for local development: +- [Open an issue](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues/new) if you encounter + any bug or to let us know if you want a new feature to be implemented. +- Spread the word about the program. +- Review the [documentation](https://{{ cookiecutter.github_user }}.github.io/{{ cookiecutter.project_slug }}) and try to improve + it. -1. Clone the repository: - ```bash - git clone https://github.com/{{ cookiecutter.__gh_slug }}.git - cd {{ cookiecutter.project_slug }} - ``` +# I know how to program in Python -2. Set up your development environment: - ```bash - # Using uv (recommended) - uv sync --all-extras --dev +If you have some python knowledge there are some additional ways to contribute. +We've ordered the [issues](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues) in +[milestones](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/milestones), check the issues in +the smaller one, as it's where we'll be spending most of our efforts. Try the +[good first +issues](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), +as they are expected to be easier to get into the project. - # Or using pip - pip install -e ".[dev]" - ``` +We develop the program with +[TDD](https://en.wikipedia.org/wiki/Test-driven_development), so we expect any +contribution to have it's associated tests. We also try to maintain an updated +[documentation](https://{{ cookiecutter.github_user }}.github.io/{{ cookiecutter.project_slug }}) of the project, so think if +your contribution needs to update it. -3. Install pre-commit hooks: - ```bash - pre-commit install - ``` +We know that the expected code quality is above average. Therefore it might +be changeling to get the initial grasp of the project structure, know how to make the +tests, update the documentation or use all the project technology stack. but please +don't let this fact discourage you from contributing: -## Testing +- If you want to develop a new feature, explain how you'd like to do it in the related issue. +- If you don't know how to test your code, do the pull request without the tests + and we'll try to do them for you. -Run tests using pytest: +# Issues + +Questions, feature requests and bug reports are all welcome as issues. +**To report a security vulnerability, please see our [security +policy](https://github.com/{{ cookiecutter.github_user }}/{{ +cookiecutter.project_slug }}/security/policy) instead.** + +To make it as simple as possible for us to help you, please include the output +of the following call in your issue: ```bash -pytest +python -c "import {{ cookiecutter.project_slug.replace('-', '_') }}.version; print({{ cookiecutter.project_slug.replace('-', '_') }}.version.version_info())" ``` -## Documentation +or if you have `make` installed, you can use `make version`. -Build the documentation locally: +Please try to always include the above unless you're unable to install `{{ +cookiecutter.project_slug }}` or know it's not relevant to your question or +feature request. -```bash -mkdocs serve -``` +# Pull Requests + +*{{ cookiecutter.project_slug }}* is released regularly so you should see your +improvements release in a matter of days or weeks. + +!!! note + Unless your change is trivial (typo, docs tweak etc.), please create an + issue to discuss the change before creating a pull request. + +If you're looking for something to get your teeth into, check out the ["help +wanted"](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +label on github. + +# Development facilities + +To make contributing as easy and fast as possible, you'll want to run tests and +linting locally. + +!!! note "" + **tl;dr**: use `make format` to fix formatting, `make` to run tests and linting & `make docs` + to build the docs. + +You'll need to have python 3.6, 3.7, or 3.8, virtualenv, git, and make installed. + +* Clone your fork and go into the repository directory: + + ```bash + git clone git@github.com:/{{ cookiecutter.project_slug }}.git + cd {{ cookiecutter.project_slug }} + ``` + +* Set up the virtualenv for running tests: + + ```bash + virtualenv -p `which python3.7` env + source env/bin/activate + ``` + +* Install `pdm` our package manager with the next command or using any of the + other [recommended + methods](https://pdm.fming.dev/latest/#recommended-installation-method). + + ```bash + curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 - + ``` + +* Install {{ cookiecutter.project_slug }}, dependencies and configure the + pre-commits: + + ```bash + make install + ``` + +* Checkout a new branch and make your changes: + + ```bash + git checkout -b my-new-feature-branch + ``` + +* Fix formatting and imports: {{ cookiecutter.project_slug }} uses + [black](https://github.com/ambv/black) to enforce formatting and + [isort](https://github.com/timothycrosley/isort) to fix imports. + + ```bash + make format + ``` + +* Run tests and linting: + + ```bash + make + ``` + + There are more sub-commands in Makefile like `test-code`, `test-examples`, + `mypy` or `security` which you might want to use, but generally `make` + should be all you need. + + If you need to pass specific arguments to pytest use the `ARGS` variable, + for example `make test ARGs='-k test_markdownlint_passes'`. + +* Build documentation: If you have changed the documentation, make sure it + builds the static site. Once built it will serve the documentation at + `localhost:8000`: + + ```bash + make docs + ``` + +* Commit, push, and create your pull request. + +* Make a new release: To generate the changelog of the new changes, build the + package, upload to pypi and clean the build files use `make bump`. -Then open `http://127.0.0.1:8000/` in your browser. -{% endif %} +We'd love you to contribute to *{{ cookiecutter.project_slug }}*! diff --git a/{{cookiecutter.project_slug}}/docs/gen_api_docs.py b/{{cookiecutter.project_slug}}/docs/gen_api_docs.py deleted file mode 100644 index c34d3be..0000000 --- a/{{cookiecutter.project_slug}}/docs/gen_api_docs.py +++ /dev/null @@ -1,69 +0,0 @@ -{% if cookiecutter.use_mkdocs == 'y' %} -#!/usr/bin/env python -""" -Script to automatically generate API documentation for the project. -This creates markdown files for each module in the project. -""" -import os -import pkgutil -import importlib -from pathlib import Path - -# Configuration -PACKAGE_NAME = "{{ cookiecutter.project_slug }}" -API_DOCS_DIR = Path("docs/api") - - -def generate_module_docs(module_name, api_dir): - """Generate documentation for a module.""" - # Create the output file path - rel_path = module_name.replace(f"{PACKAGE_NAME}.", "").replace(".", "/") - output_path = api_dir / f"{rel_path}.md" - - # Create parent directories if they don't exist - output_path.parent.mkdir(parents=True, exist_ok=True) - - # Create the markdown content - content = f"# {module_name}\n\n::: {module_name}\n" - - # Write the content to the file - with open(output_path, "w") as f: - f.write(content) - - print(f"Generated docs for {module_name} at {output_path}") - - -def discover_modules(package_name): - """Discover all modules in the package.""" - package = importlib.import_module(package_name) - modules = [package_name] - - if hasattr(package, "__path__"): - for _, name, is_pkg in pkgutil.iter_modules(package.__path__, f"{package_name}."): - modules.append(name) - if is_pkg: - modules.extend(discover_modules(name)) - - return modules - - -def main(): - """Main function to generate API documentation.""" - # Ensure the API docs directory exists - api_dir = Path(API_DOCS_DIR) - api_dir.mkdir(parents=True, exist_ok=True) - - # Discover all modules - modules = discover_modules(PACKAGE_NAME) - - # Generate documentation for each module - for module_name in modules: - try: - generate_module_docs(module_name, api_dir) - except Exception as e: - print(f"Error generating docs for {module_name}: {e}") - - -if __name__ == "__main__": - main() -{% endif %} diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md index 08989af..8ad32ec 100644 --- a/{{cookiecutter.project_slug}}/docs/index.md +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -1,4 +1,3 @@ -{% if cookiecutter.use_mkdocs == 'y' %} # {{ cookiecutter.project_name }} {{ cookiecutter.project_short_description }} @@ -24,4 +23,3 @@ from {{ cookiecutter.project_slug }} import example ## License {{ cookiecutter.open_source_license }} -{% endif %} From 25edea95e2b743aa570681dddae4db59ea034802 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:26:54 +0200 Subject: [PATCH 06/15] add version file --- .../{{cookiecutter.project_slug}}/version.py | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 {{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py diff --git a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py new file mode 100644 index 0000000..6349b49 --- /dev/null +++ b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py @@ -0,0 +1,21 @@ +"""Utilities to retrieve the information of the program version.""" + +import platform +import sys +from textwrap import dedent + +# Do not edit the version manually, let `make bump` do it. + +__version__ = "0.1.0" + + +def version_info() -> str: + """Display the version of the program, python and the platform.""" + return dedent( + f"""\ + ------------------------------------------------------------------ + {{cookiecutter.project_underscore_slug}}: {__version__} + Python: {sys.version.split(" ", maxsplit=1)[0]} + Platform: {platform.platform()} + ------------------------------------------------------------------""" + ) From 2fad7335ed3da26e9c9a2a90e0a463ef229eb328 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:27:04 +0200 Subject: [PATCH 07/15] add project description in init --- .../src/{{cookiecutter.project_slug}}/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py index e69de29..b3c5247 100644 --- a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py +++ b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py @@ -0,0 +1 @@ +"""{{ cookiecutter.project_description }}.""" From f3d7a5ee4698ab35ee2c38d92fb0f1d0968cccf0 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:27:19 +0200 Subject: [PATCH 08/15] improve pyproject tool config (black and isort) --- {{cookiecutter.project_slug}}/pyproject.toml | 25 ++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 3a1f4ec..13da2ec 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -51,6 +51,7 @@ addopts = "-ra --cov=src" [tool.coverage.report] exclude_also = [ + 'pragma: no cover', 'def __repr__', 'raise NotImplementedError', 'if TYPE_CHECKING:', @@ -69,5 +70,29 @@ tag_format = "v${version}" version_scheme = "semver" update_changelog_on_bump = true +[tool.black] +line-length = 88 +target-version = ['py310', 'py311', 'py312', 'py313'] +include = '\.pyi?$' +exclude = ''' +/( + \.eggs + | \.git + | \.hg + | \.mypy_cache + | \.tox + | \.venv + | _build + | buck-out + | build + | dist + # The following are specific to Black, you probably don't want those. + | blib2to3 + | tests/data + | profiling +)/ +''' + [tool.isort] profile = "black" +src_paths = ["src", "test"] From f8a09e02e64acf5746c44f82487982e5d67ef660 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:27:33 +0200 Subject: [PATCH 09/15] include security_advisories_email cookiecutter param --- cookiecutter.json | 1 + 1 file changed, 1 insertion(+) diff --git a/cookiecutter.json b/cookiecutter.json index 86b094b..f288adc 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -27,5 +27,6 @@ "GNU General Public License v3", "Not open source" ], + "security_advisories_email": "{{ cookiecutter.author_email }}", "__gh_slug": "{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}" } From c081dc1fa354bc762f7e775aa354d86bb9cb161d Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:41:28 +0200 Subject: [PATCH 10/15] fix cookiecutter vars --- cookiecutter.json | 2 +- .../.github/ISSUE_TEMPLATE/question.md | 2 +- .../docs/contributing.md | 16 ++++++++-------- {{cookiecutter.project_slug}}/mkdocs.yml | 4 +--- .../{{cookiecutter.project_slug}}/__init__.py | 2 +- .../src/{{cookiecutter.project_slug}}/version.py | 12 +++++++----- 6 files changed, 19 insertions(+), 19 deletions(-) diff --git a/cookiecutter.json b/cookiecutter.json index f288adc..34382fa 100644 --- a/cookiecutter.json +++ b/cookiecutter.json @@ -27,6 +27,6 @@ "GNU General Public License v3", "Not open source" ], - "security_advisories_email": "{{ cookiecutter.author_email }}", + "security_advisories_email": "{{ cookiecutter.email }}", "__gh_slug": "{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}" } diff --git a/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md index 2b682be..97f6918 100644 --- a/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md +++ b/{{cookiecutter.project_slug}}/.github/ISSUE_TEMPLATE/question.md @@ -8,7 +8,7 @@ labels: question * [ ] I added a descriptive title to this issue. * [ ] I have searched (google, github) for similar issues and couldn't find anything. -* [ ] I have read and followed [the docs](https://{{ cookiecutter.github_user }}.github.io/{{ cookiecutter.project_slug }}) +* [ ] I have read and followed [the docs](https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}) and couldn't find an answer. --> diff --git a/{{cookiecutter.project_slug}}/docs/contributing.md b/{{cookiecutter.project_slug}}/docs/contributing.md index 6659339..457d0df 100644 --- a/{{cookiecutter.project_slug}}/docs/contributing.md +++ b/{{cookiecutter.project_slug}}/docs/contributing.md @@ -6,26 +6,26 @@ different ways to do so. There are several ways you can contribute: -- [Open an issue](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues/new) if you encounter +- [Open an issue](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues/new) if you encounter any bug or to let us know if you want a new feature to be implemented. - Spread the word about the program. -- Review the [documentation](https://{{ cookiecutter.github_user }}.github.io/{{ cookiecutter.project_slug }}) and try to improve +- Review the [documentation](https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}) and try to improve it. # I know how to program in Python If you have some python knowledge there are some additional ways to contribute. -We've ordered the [issues](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues) in -[milestones](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/milestones), check the issues in +We've ordered the [issues](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues) in +[milestones](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/milestones), check the issues in the smaller one, as it's where we'll be spending most of our efforts. Try the [good first -issues](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), +issues](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22), as they are expected to be easier to get into the project. We develop the program with [TDD](https://en.wikipedia.org/wiki/Test-driven_development), so we expect any contribution to have it's associated tests. We also try to maintain an updated -[documentation](https://{{ cookiecutter.github_user }}.github.io/{{ cookiecutter.project_slug }}) of the project, so think if +[documentation](https://{{ cookiecutter.github_username }}.github.io/{{ cookiecutter.project_slug }}) of the project, so think if your contribution needs to update it. We know that the expected code quality is above average. Therefore it might @@ -41,7 +41,7 @@ don't let this fact discourage you from contributing: Questions, feature requests and bug reports are all welcome as issues. **To report a security vulnerability, please see our [security -policy](https://github.com/{{ cookiecutter.github_user }}/{{ +policy](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/security/policy) instead.** To make it as simple as possible for us to help you, please include the output @@ -67,7 +67,7 @@ improvements release in a matter of days or weeks. issue to discuss the change before creating a pull request. If you're looking for something to get your teeth into, check out the ["help -wanted"](https://github.com/{{ cookiecutter.github_user }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) +wanted"](https://github.com/{{ cookiecutter.github_username }}/{{ cookiecutter.project_slug }}/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label on github. # Development facilities diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index ab09a50..f96001b 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -1,4 +1,3 @@ -{% if cookiecutter.use_mkdocs == 'y' %} site_name: {{ cookiecutter.project_name }} site_description: {{ cookiecutter.project_short_description }} site_author: {{ cookiecutter.full_name }} @@ -51,6 +50,5 @@ plugins: nav: - Home: index.md - - API Reference: api/ + - API Reference: api - Contributing: contributing.md -{% endif %} diff --git a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py index b3c5247..981459f 100644 --- a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py +++ b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/__init__.py @@ -1 +1 @@ -"""{{ cookiecutter.project_description }}.""" +"""{{ cookiecutter.project_short_description }}.""" diff --git a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py index 6349b49..00eb123 100644 --- a/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py +++ b/{{cookiecutter.project_slug}}/src/{{cookiecutter.project_slug}}/version.py @@ -1,21 +1,23 @@ """Utilities to retrieve the information of the program version.""" -import platform -import sys -from textwrap import dedent - # Do not edit the version manually, let `make bump` do it. __version__ = "0.1.0" def version_info() -> str: + import platform + import sys + from textwrap import dedent """Display the version of the program, python and the platform.""" return dedent( f"""\ ------------------------------------------------------------------ - {{cookiecutter.project_underscore_slug}}: {__version__} + {{cookiecutter.project_slug}}: {__version__} Python: {sys.version.split(" ", maxsplit=1)[0]} Platform: {platform.platform()} ------------------------------------------------------------------""" ) + +if __name__ == "__main__": + print(version_info()) From 2661e90833be19bc326abba5b1202dc67a912361 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:41:41 +0200 Subject: [PATCH 11/15] test version --- tests/test_template.py | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/tests/test_template.py b/tests/test_template.py index ce6e668..a008fe0 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -69,6 +69,21 @@ def run_command( text=True, ) +@pytest.mark.parametrize("project", ["minimalist"], indirect=True) +def test_version(project: Result): + project_path = project.project_path + assert project_path is not None + project_name = os.path.basename(project_path) + version_file = project_path / "src" / project_name / "version.py" + + process = run_command(f"uv run python {version_file}", project_path) + + assert process.returncode == 0, f"Version failed with error: {process.stderr}" + + assert ( + project_name in process.stdout + ), f"Expected welcome message not found in output: {process.stdout}" + @pytest.mark.parametrize("project", ["click", "argparse", "minimalist"], indirect=True) def test_main_entrypoint(project: Result): From d99d7a4cc1f1263a260b1bcbaa6b0644aa976c06 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 20:44:57 +0200 Subject: [PATCH 12/15] format --- {{cookiecutter.project_slug}}/.github/workflows/docs.yml | 2 -- {{cookiecutter.project_slug}}/README.md | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml index 84e9493..baf0ed6 100644 --- a/{{cookiecutter.project_slug}}/.github/workflows/docs.yml +++ b/{{cookiecutter.project_slug}}/.github/workflows/docs.yml @@ -1,4 +1,3 @@ -{% if cookiecutter.use_mkdocs == 'y' %} name: docs on: @@ -58,4 +57,3 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 -{% endif %} diff --git a/{{cookiecutter.project_slug}}/README.md b/{{cookiecutter.project_slug}}/README.md index 14e2670..4544e28 100644 --- a/{{cookiecutter.project_slug}}/README.md +++ b/{{cookiecutter.project_slug}}/README.md @@ -4,4 +4,4 @@ {% if cookiecutter.use_mkdocs == 'y' %} [docs](https://{{cookiecutter.github_username}}.github.io/{{cookiecutter.project_slug}}) -{% endif %} +{%- endif %} From de3d2697370d2989ab918cce76d1149e596c17f9 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 21:20:42 +0200 Subject: [PATCH 13/15] improve mkdocs config --- .../docs/api/index.md | 5 -- .../docs/contributing.md | 34 +++----------- {{cookiecutter.project_slug}}/docs/index.md | 2 - .../docs/reference.md | 1 + {{cookiecutter.project_slug}}/mkdocs.yml | 47 ++++++++++++++++--- {{cookiecutter.project_slug}}/pyproject.toml | 6 +++ 6 files changed, 54 insertions(+), 41 deletions(-) delete mode 100644 {{cookiecutter.project_slug}}/docs/api/index.md create mode 100644 {{cookiecutter.project_slug}}/docs/reference.md diff --git a/{{cookiecutter.project_slug}}/docs/api/index.md b/{{cookiecutter.project_slug}}/docs/api/index.md deleted file mode 100644 index a121eae..0000000 --- a/{{cookiecutter.project_slug}}/docs/api/index.md +++ /dev/null @@ -1,5 +0,0 @@ -# API Reference - -This section contains auto-generated API reference documentation. - -::: {{ cookiecutter.project_slug }} diff --git a/{{cookiecutter.project_slug}}/docs/contributing.md b/{{cookiecutter.project_slug}}/docs/contributing.md index 457d0df..3855430 100644 --- a/{{cookiecutter.project_slug}}/docs/contributing.md +++ b/{{cookiecutter.project_slug}}/docs/contributing.md @@ -48,11 +48,9 @@ To make it as simple as possible for us to help you, please include the output of the following call in your issue: ```bash -python -c "import {{ cookiecutter.project_slug.replace('-', '_') }}.version; print({{ cookiecutter.project_slug.replace('-', '_') }}.version.version_info())" +uv run src/{{ cookiecutter.project_slug }}/version.py ``` -or if you have `make` installed, you can use `make version`. - Please try to always include the above unless you're unable to install `{{ cookiecutter.project_slug }}` or know it's not relevant to your question or feature request. @@ -75,11 +73,8 @@ label on github. To make contributing as easy and fast as possible, you'll want to run tests and linting locally. -!!! note "" - **tl;dr**: use `make format` to fix formatting, `make` to run tests and linting & `make docs` - to build the docs. - -You'll need to have python 3.6, 3.7, or 3.8, virtualenv, git, and make installed. +You'll need to have python 3.10, 3.11, 3.12, or 3.13, uv and git installed. The +nix package manager is also recommended. * Clone your fork and go into the repository directory: @@ -91,25 +86,10 @@ You'll need to have python 3.6, 3.7, or 3.8, virtualenv, git, and make installed * Set up the virtualenv for running tests: ```bash - virtualenv -p `which python3.7` env + uv sync source env/bin/activate ``` -* Install `pdm` our package manager with the next command or using any of the - other [recommended - methods](https://pdm.fming.dev/latest/#recommended-installation-method). - - ```bash - curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 - - ``` - -* Install {{ cookiecutter.project_slug }}, dependencies and configure the - pre-commits: - - ```bash - make install - ``` - * Checkout a new branch and make your changes: ```bash @@ -121,13 +101,13 @@ You'll need to have python 3.6, 3.7, or 3.8, virtualenv, git, and make installed [isort](https://github.com/timothycrosley/isort) to fix imports. ```bash - make format + uv run black ``` * Run tests and linting: ```bash - make + uv run pre-commit ``` There are more sub-commands in Makefile like `test-code`, `test-examples`, @@ -142,7 +122,7 @@ You'll need to have python 3.6, 3.7, or 3.8, virtualenv, git, and make installed `localhost:8000`: ```bash - make docs + mkdocs serve ``` * Commit, push, and create your pull request. diff --git a/{{cookiecutter.project_slug}}/docs/index.md b/{{cookiecutter.project_slug}}/docs/index.md index 8ad32ec..a848124 100644 --- a/{{cookiecutter.project_slug}}/docs/index.md +++ b/{{cookiecutter.project_slug}}/docs/index.md @@ -1,5 +1,3 @@ -# {{ cookiecutter.project_name }} - {{ cookiecutter.project_short_description }} ## Installation diff --git a/{{cookiecutter.project_slug}}/docs/reference.md b/{{cookiecutter.project_slug}}/docs/reference.md new file mode 100644 index 0000000..c012b1c --- /dev/null +++ b/{{cookiecutter.project_slug}}/docs/reference.md @@ -0,0 +1 @@ +::: {{ cookiecutter.project_slug }} diff --git a/{{cookiecutter.project_slug}}/mkdocs.yml b/{{cookiecutter.project_slug}}/mkdocs.yml index f96001b..f19f8ab 100644 --- a/{{cookiecutter.project_slug}}/mkdocs.yml +++ b/{{cookiecutter.project_slug}}/mkdocs.yml @@ -25,18 +25,44 @@ theme: - navigation.tracking - navigation.expand - navigation.indexes + - navigation.top + - navigation.footer - content.code.copy + - content.code.annotate markdown_extensions: - - pymdownx.highlight: - anchor_linenums: true - - pymdownx.superfences - - pymdownx.inlinehilite - - pymdownx.snippets + - abbr + - def_list - admonition + # We need the markdown-include to inject files into other files + - markdown_include.include: + base_path: docs + - meta + - toc: + permalink: true + baselevel: 2 + - pymdownx.arithmatex + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.critic - pymdownx.details + - pymdownx.emoji: + emoji_generator: '!!python/name:pymdownx.emoji.to_svg' + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.mark + - pymdownx.smartsymbols + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.tabbed: alternate_style: true + - pymdownx.tasklist: + custom_checkbox: true + - pymdownx.tilde plugins: - search @@ -47,8 +73,15 @@ plugins: show_source: true show_submodules: true docstring_style: google + - autolinks + - git-revision-date-localized: + type: timeago + fallback_to_build_date: true + - minify: + minify_html: true + - section-index nav: - - Home: index.md - - API Reference: api + - {{ cookiecutter.project_name }}: index.md + - Reference: reference.md - Contributing: contributing.md diff --git a/{{cookiecutter.project_slug}}/pyproject.toml b/{{cookiecutter.project_slug}}/pyproject.toml index 13da2ec..2ab1c07 100644 --- a/{{cookiecutter.project_slug}}/pyproject.toml +++ b/{{cookiecutter.project_slug}}/pyproject.toml @@ -36,8 +36,14 @@ dev = [ ] {%- if cookiecutter.use_mkdocs == "y" %} docs = [ + "markdown-include", "mkdocs", + "mkdocs-autolinks-plugin", + "mkdocs-git-revision-date-localized-plugin", + "mkdocs-htmlproofer-plugin", "mkdocs-material", + "mkdocs-minify-plugin", + "mkdocs-section-index", "mkdocstrings", "mkdocstrings-python", ] From 7ac814400bdb752597ff5a8b4f879fdb4a072d69 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 21:25:26 +0200 Subject: [PATCH 14/15] fix flake python package overrides --- {{cookiecutter.project_slug}}/flake.nix | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/{{cookiecutter.project_slug}}/flake.nix b/{{cookiecutter.project_slug}}/flake.nix index 39ba129..67e870d 100644 --- a/{{cookiecutter.project_slug}}/flake.nix +++ b/{{cookiecutter.project_slug}}/flake.nix @@ -45,6 +45,14 @@ # Add necessary overrides # https://pyproject-nix.github.io/uv2nix/overriding/index.html }); + csscompressor = prev.csscompressor.overrideAttrs (old: { + nativeBuildInputs = old.nativeBuildInputs + ++ [ (final.resolveBuildSystem { setuptools = [ ]; }) ]; + }); + jsmin = prev.csscompressor.overrideAttrs (old: { + nativeBuildInputs = old.nativeBuildInputs + ++ [ (final.resolveBuildSystem { setuptools = [ ]; }) ]; + }); }; pkgs = nixpkgs.legacyPackages.x86_64-linux; From 70e0a4a4702dab03b8fc0e4e0d003bd8a7ac4c06 Mon Sep 17 00:00:00 2001 From: haztecaso Date: Tue, 29 Jul 2025 21:29:33 +0200 Subject: [PATCH 15/15] test nix build --- tests/test_template.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/tests/test_template.py b/tests/test_template.py index a008fe0..65a7e1f 100644 --- a/tests/test_template.py +++ b/tests/test_template.py @@ -82,8 +82,17 @@ def test_version(project: Result): assert ( project_name in process.stdout - ), f"Expected welcome message not found in output: {process.stdout}" + ), f"Expected '{project_name}' not found in output: {process.stdout}" +@pytest.mark.parametrize("project", ["default", "minimalist"], indirect=True) +def test_nix_build(project: Result): + project_path = project.project_path + assert project_path is not None + + process = run_command(f"nix build", project_path) + + assert process.returncode == 0, f"Version failed with error: {process.stderr}" + @pytest.mark.parametrize("project", ["click", "argparse", "minimalist"], indirect=True) def test_main_entrypoint(project: Result):