Skip to content

Commit 93decda

Browse files
committed
docs: add notes at top of page, update REAMDE
Signed-off-by: Henry Schreiner <[email protected]>
1 parent 4555a59 commit 93decda

File tree

3 files changed

+28
-10
lines changed

3 files changed

+28
-10
lines changed

README.md

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,17 +15,18 @@ templates for Python packages?
1515

1616
- Lives with the [Scientific-Python Development Guide][]: Every decision is
1717
clearly documented and every tool described, and everything is kept in sync.
18-
- Nine different backends to choose from for building packages.
18+
- Ten different backends to choose from for building packages.
1919
- Optional VCS versioning for most backends.
20+
- Selection for your preferred documentation engine (Sphinx or MkDocs).
2021
- Template generation tested in GitHub Actions using nox.
2122
- Supports generation with [copier][], [cookiecutter][], and [cruft][].
2223
- Supports GitHub Actions if targeting a `github.com` url (the default), and
2324
adds experimental GitLab CI support otherwise.
2425
- Includes several compiled backends using [pybind11][], with wheels produced
2526
for all platforms using [cibuildwheel][].
2627
- Provides [`sp-repo-review`][pypi-link] to evaluate existing repos against the
27-
guidelines, with a WebAssembly version integrated with the guide. All checks
28-
cross-linked.
28+
guidelines, with a WebAssembly version integrated with the guide. Checks are
29+
hyperlinked back to the guide.
2930
- Follows [PyPA][] best practices and regularly updated. Recent additions:
3031
- [PEP 639](https://peps.python.org/pep-0639): SPDX licenses
3132
- [PEP 735](https://peps.python.org/pep-0735): Dependency groups
@@ -134,22 +135,28 @@ backports structure with a small typing example.
134135
- GitHub Actions runs testing for the generation itself
135136
- Uses nox so cookie development can be checked locally
136137
- Uses uv for high performance CI
137-
- GitHub actions deploy
138+
- GitHub actions deployment
138139
- C++ backends include cibuildwheel for wheel builds
139140
- Uses PyPI trusted publisher deployment
141+
- A GitHub release configuration that skips common bot commits when
142+
auto-generating release notes
140143
- Dependabot keeps actions up to date periodically, through useful pull requests
141-
- Formatting handled by pre-commit
144+
- A contributing guide
145+
- Formatting handled by pre-commit or prek
142146
- No reason not to be strict on a new project; remove what you don't want.
143147
- Includes MyPy - static typing
144148
- Includes Ruff - standard formatting, linting and autofixes
145149
- Replaces Flake8, isort, pyupgrade, yesqa, pycln, and dozens of plugins
146150
- Includes spell checking
151+
- One of several popular licenses
147152
- An pylint nox target can be used to run pylint, which integrated GHA
148153
annotations
149-
- A ReadTheDocs-ready Sphinx docs folder and `docs` dependency-group
150-
- A test folder and pytest `test` dependency-group
154+
- A ReadTheDocs-ready Sphinx or MkDocs `docs/` folder and `docs`
155+
dependency-group
156+
- A `tests/` folder and pytest `test` dependency-group
151157
- A dev group for `uv run` integration
152158
- A noxfile is included with a few common targets
159+
- A README
153160

154161
#### For developers:
155162

docs/pages/guides/packaging_compiled.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ with render_cookie(backend="maturin", vcs=False) as maturin:
2626
]]] -->
2727
<!-- [[[end]]] -->
2828

29+
{: .note }
30+
31+
Once you've done this at least once, feel free to use
32+
[our cookiecutter/copier template](https://github.com/scientific-python/cookie),
33+
or `uv init` to get started quickly on new packages!
34+
2935
# Packaging Compiled Projects
3036

3137
There are a variety of ways to package compiled projects. In the past, the only

docs/pages/guides/packaging_simple.md

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,12 @@ parent: Topical Guides
88

99
{% include toc.html %}
1010

11+
{: .note }
12+
13+
Once you've done this at least once, feel free to use
14+
[our cookiecutter/copier template](https://github.com/scientific-python/cookie),
15+
or `uv init` to get started quickly on new packages!
16+
1117
# Simple packaging
1218

1319
Python packages can now use a modern build system instead of the classic but
@@ -113,9 +119,8 @@ If you don't match your package name and import name (which you should except
113119
for very special cases), you will likely need extra configuration here.
114120

115121
You should have a `README` {% rr PY002 %} and a `LICENSE` {% rr PY003 %} file.
116-
You should have a `docs/` folder {%
117-
rr PY004 %}. You should have a `/tests` folder {%
118-
rr PY005 %} (recommended) and/or a `src/<package>/tests` folder.
122+
You should have a `docs/` folder {% rr PY004 %}. You should have a `/tests`
123+
folder {% rr PY005 %} (recommended) and/or a `src/<package>/tests` folder.
119124

120125
## Versioning
121126

0 commit comments

Comments
 (0)