diff --git a/README.md b/README.md index 9b55f2e0..d720dcf0 100644 --- a/README.md +++ b/README.md @@ -15,8 +15,9 @@ templates for Python packages? - Lives with the [Scientific-Python Development Guide][]: Every decision is clearly documented and every tool described, and everything is kept in sync. -- Nine different backends to choose from for building packages. +- Ten different backends to choose from for building packages. - Optional VCS versioning for most backends. +- Selection for your preferred documentation engine (Sphinx or MkDocs). - Template generation tested in GitHub Actions using nox. - Supports generation with [copier][], [cookiecutter][], and [cruft][]. - Supports GitHub Actions if targeting a `github.com` url (the default), and @@ -24,8 +25,8 @@ templates for Python packages? - Includes several compiled backends using [pybind11][], with wheels produced for all platforms using [cibuildwheel][]. - Provides [`sp-repo-review`][pypi-link] to evaluate existing repos against the - guidelines, with a WebAssembly version integrated with the guide. All checks - cross-linked. + guidelines, with a WebAssembly version integrated with the guide. Checks are + hyperlinked back to the guide. - Follows [PyPA][] best practices and regularly updated. Recent additions: - [PEP 639](https://peps.python.org/pep-0639): SPDX licenses - [PEP 735](https://peps.python.org/pep-0735): Dependency groups @@ -134,22 +135,28 @@ backports structure with a small typing example. - GitHub Actions runs testing for the generation itself - Uses nox so cookie development can be checked locally - Uses uv for high performance CI -- GitHub actions deploy +- GitHub actions deployment - C++ backends include cibuildwheel for wheel builds - Uses PyPI trusted publisher deployment +- A GitHub release configuration that skips common bot commits when + auto-generating release notes - Dependabot keeps actions up to date periodically, through useful pull requests -- Formatting handled by pre-commit +- A contributing guide +- Formatting handled by pre-commit or prek - No reason not to be strict on a new project; remove what you don't want. - Includes MyPy - static typing - Includes Ruff - standard formatting, linting and autofixes - Replaces Flake8, isort, pyupgrade, yesqa, pycln, and dozens of plugins - Includes spell checking +- One of several popular licenses - An pylint nox target can be used to run pylint, which integrated GHA annotations -- A ReadTheDocs-ready Sphinx docs folder and `docs` dependency-group -- A test folder and pytest `test` dependency-group +- A ReadTheDocs-ready Sphinx or MkDocs `docs/` folder and `docs` + dependency-group +- A `tests/` folder and pytest `test` dependency-group - A dev group for `uv run` integration - A noxfile is included with a few common targets +- A README #### For developers: diff --git a/docs/pages/guides/packaging_compiled.md b/docs/pages/guides/packaging_compiled.md index b39fbc7d..da444c21 100644 --- a/docs/pages/guides/packaging_compiled.md +++ b/docs/pages/guides/packaging_compiled.md @@ -26,6 +26,14 @@ with render_cookie(backend="maturin", vcs=False) as maturin: ]]] --> +{: .highlight-title } + +> Quick start +> +> Once you've done this at least once, feel free to use +> [our cookiecutter/copier template](https://github.com/scientific-python/cookie), +> or `uv init` to get started quickly on new packages! + # Packaging Compiled Projects There are a variety of ways to package compiled projects. In the past, the only @@ -53,15 +61,18 @@ There are also classic setuptools plugins: - [scikit-build][]: Builds C/C++/Fortran using CMake. - [setuptools-rust][]: Builds Rust using Cargo. -{: .important } - -Selecting a backend: If you are using Rust, use maturin. If you are using CUDA, -use scikit-build-core. If you are using a classic language (C, C++, Fortran), -then you can use either scikit-build-core or meson-python, depending on whether -you prefer writing CMake or Meson. Meson is a lot more opinionated; it requires -you use version control, it requires a README.md and LICENSE file. It requires -your compiler be properly set up. Etc. While CMake can be as elegant as Meson, -there are a lot of historical examples of poorly written CMake. +{: .highlight-title } + +> Selecting a backend +> +> Selecting a backend: If you are using Rust, use maturin. If you are using +> CUDA, use scikit-build-core. If you are using a classic language (C, C++, +> Fortran), then you can use either scikit-build-core or meson-python, depending +> on whether you prefer writing CMake or Meson. Meson is a lot more opinionated; +> it requires you use version control, it requires a README.md and LICENSE file. +> It requires your compiler be properly set up. Etc. While CMake can be as +> elegant as Meson, there are a lot of historical examples of poorly written +> CMake. ## pyproject.toml: build-system diff --git a/docs/pages/guides/packaging_simple.md b/docs/pages/guides/packaging_simple.md index 4d0bef36..b22b7766 100644 --- a/docs/pages/guides/packaging_simple.md +++ b/docs/pages/guides/packaging_simple.md @@ -8,6 +8,14 @@ parent: Topical Guides {% include toc.html %} +{: .highlight-title } + +> Quick start +> +> Once you've done this at least once, feel free to use +> [our cookiecutter/copier template](https://github.com/scientific-python/cookie), +> or `uv init` to get started quickly on new packages! + # Simple packaging Python packages can now use a modern build system instead of the classic but @@ -32,7 +40,7 @@ tutorial][]. > `pipx run hatch new --init` or with > [ini2toml](https://ini2toml.readthedocs.io/en/latest/). -{: .highlight-title } +{: .important-title } > Selecting a backend > @@ -113,9 +121,8 @@ If you don't match your package name and import name (which you should except for very special cases), you will likely need extra configuration here. You should have a `README` {% rr PY002 %} and a `LICENSE` {% rr PY003 %} file. -You should have a `docs/` folder {% -rr PY004 %}. You should have a `/tests` folder {% -rr PY005 %} (recommended) and/or a `src//tests` folder. +You should have a `docs/` folder {% rr PY004 %}. You should have a `/tests` +folder {% rr PY005 %} (recommended) and/or a `src//tests` folder. ## Versioning