Skip to content

Commit 119df57

Browse files
febus982febus982
committed
Add documentation
1 parent 09e8b2d commit 119df57

2 files changed

Lines changed: 100 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,11 +14,60 @@
1414
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
1515
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)
1616

17+
This template repository provides the boilerplate to create a python package.
18+
It is configured with all the following features:
19+
20+
* Test suite using [pytest](https://docs.pytest.org/en/7.4.x/)
21+
* Typing using [mypy](https://mypy.readthedocs.io/en/stable/)
22+
* Linting using [ruff](https://github.com/astral-sh/ruff)
23+
* Code formatter using [black](https://pypi.org/project/black/)
24+
* Integration with CodeClimate for code quality and coverage checks
25+
* CI pipeline supporting:
26+
* testing against multiple python versions
27+
* releases on [PyPI](https://pypi.org)
28+
* GitHub pages documentation using [mkdocs](https://www.mkdocs.org)
29+
30+
This project doesn't currently use [tox](https://tox.wiki/en/4.11.4/index.html) or other matrix
31+
testing utilities. I prefer to run the tests only against the latest python locally, and run
32+
previous python versions directly in the CI pipeline to catch these bugs.
33+
34+
## How to use this repository template to create a new package
35+
36+
* Create your github repository using this template. (The big green `Use this template` button)
37+
* Rename the `bootstrap_python_package` directory
38+
* Search and replace all the occurrences of `bootstrap-python-package` and `bootstrap_python_package`
39+
* Configure a pending trusted publisher on [pypi](https://pypi.org/manage/account/publishing) using the following values:
40+
* PyPI Project Name: what you renamed the directory `bootstrap_python_package` to (Double check `_` and `-`)
41+
* Owner: The github repository owner (in this case `febus982`)
42+
* Repository name: The github repository name (in this case `bootstrap-python-package`)
43+
* Workflow name: `release.yml`
44+
* Create a github actions secret named `CODECLIMATE_REPORTER_ID` (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions)
45+
containing the codeclimate reporter id (you can find it at https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter).
46+
If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.
47+
* Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)
48+
49+
50+
## Package release
51+
52+
This setup uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning).
53+
This means it's not necessary to commit the version in the code but the CI pipeline
54+
will infer it from the git tag.
55+
56+
To release a new version, just create a new release in the github repository. It will
57+
create a new tag and do all the magic.
58+
59+
**IMPORTANT:** The default configuration requires the release name and the tag to follow
60+
the convention `vX.X.X` (semantic versioning preceded by lowercase `v`). It will publish
61+
the correct version on Pypi, omitting the `v` (ie. `v1.0.0` will publish `1.0.0`).
62+
63+
This format can be customized, refer to [poetry-dynamic-versioning docs](https://github.com/mtkennerly/poetry-dynamic-versioning)
1764

1865
## Commands for development
1966

67+
All the common commands used during development can be run using make targets:
68+
2069
* `make dev-dependencies`: Install dev requirements
2170
* `make test`: Run test suite
2271
* `make check`: Run tests, code style and lint checks
23-
* `make fix`: Run tests, code style and lint checks with automatic fixes (where possible)
72+
* `make fix`: Run code style and lint automatic fixes (where possible)
2473
* `make docs`: Render the mkdocs website locally

‎docs/index.md‎

Lines changed: 50 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,59 @@
11
# bootstrap-python-package
22

3+
This template repository provides the boilerplate to create a python package.
4+
It is configured with all the following features:
5+
6+
* Test suite using [pytest](https://docs.pytest.org/en/7.4.x/)
7+
* Typing using [mypy](https://mypy.readthedocs.io/en/stable/)
8+
* Linting using [ruff](https://github.com/astral-sh/ruff)
9+
* Code formatter using [black](https://pypi.org/project/black/)
10+
* Integration with CodeClimate for code quality and coverage checks
11+
* CI pipeline supporting:
12+
* testing against multiple python versions
13+
* releases on [PyPI](https://pypi.org)
14+
* GitHub pages documentation using [mkdocs](https://www.mkdocs.org)
15+
16+
This project doesn't currently use [tox](https://tox.wiki/en/4.11.4/index.html) or other matrix
17+
testing utilities. I prefer to run the tests only against the latest python locally, and run
18+
previous python versions directly in the CI pipeline to catch these bugs.
19+
20+
## How to use this repository template to create a new package
21+
22+
* Create your github repository using this template. (The big green `Use this template` button)
23+
* Rename the `bootstrap_python_package` directory
24+
* Search and replace all the occurrences of `bootstrap-python-package` and `bootstrap_python_package`
25+
* Configure a pending trusted publisher on [pypi](https://pypi.org/manage/account/publishing) using the following values:
26+
* PyPI Project Name: what you renamed the directory `bootstrap_python_package` to (Double check `_` and `-`)
27+
* Owner: The github repository owner (in this case `febus982`)
28+
* Repository name: The github repository name (in this case `bootstrap-python-package`)
29+
* Workflow name: `release.yml`
30+
* Create a github actions secret named `CODECLIMATE_REPORTER_ID` (at URL https://github.com/GITHUB_NAME_OR_ORGANIZATION/GITHUB_REPOSITORY/settings/secrets/actions)
31+
containing the codeclimate reporter id (you can find it at https://codeclimate.com/repos/YOUR_REPO_ID/settings/test_reporter).
32+
If you don't want to use CodeClimate just delete `workflows/python-quality.yml`.
33+
* Update the badges in `README.md`! (check [shields.io](https://shields.io/) for extra badges)
34+
35+
36+
## Package release
37+
38+
This setup uses [poetry-dynamic-versioning](https://github.com/mtkennerly/poetry-dynamic-versioning).
39+
This means it's not necessary to commit the version in the code but the CI pipeline
40+
will infer it from the git tag.
41+
42+
To release a new version, just create a new release in the github repository. It will
43+
create a new tag and do all the magic.
44+
45+
**IMPORTANT:** The default configuration requires the release name and the tag to follow
46+
the convention `vX.X.X` (semantic versioning preceded by lowercase `v`). It will publish
47+
the correct version on Pypi, omitting the `v` (ie. `v1.0.0` will publish `1.0.0`).
48+
49+
This format can be customized, refer to [poetry-dynamic-versioning docs](https://github.com/mtkennerly/poetry-dynamic-versioning)
350

451
## Commands for development
552

53+
All the common commands used during development can be run using make targets:
54+
655
* `make dev-dependencies`: Install dev requirements
756
* `make test`: Run test suite
857
* `make check`: Run tests, code style and lint checks
9-
* `make fix`: Run tests, code style and lint checks with automatic fixes (where possible)
58+
* `make fix`: Run code style and lint automatic fixes (where possible)
1059
* `make docs`: Render the mkdocs website locally

0 commit comments

Comments
 (0)