fix: more cog & mention build-and-inspect-python-package (#212)

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

Author: henryiii

.pre-commit-config.yaml

@@ -89,5 +89,5 @@ repos:
         name: Cog the pages
         language: python
         entry: cog -P -r -I ./helpers
-        files: "^docs/pages/guides/packaging_compiled.md"
+        files: "^docs/pages/guides/(packaging_compiled|docs).md"
         additional_dependencies: [cogapp, cookiecutter]

docs/pages/guides/coverage.md

@@ -103,17 +103,31 @@ One can also configure `Codecov` and coverage reports passed to `Codecov` using
 with your `workflows` folder. Additionally, `Codecov` allows you to create and
 edit this `YAML` file directly through your `Codecov` project's settings!
 
-A recommended configuration for `Codecov`:
+A recommended configuration for `.github/codecov.yml`:
 
 ```yaml
 codecov:
   notify:
     after_n_builds: x
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 5%
+    patch:
+      default:
+        informational: true
 ```
 
 where `x` is the number of uploaded reports `Codecov` should wait to receive
 before sending statuses. This would ensure that the `Codecov` checks don't fail
-before all the coverage reports are uploaded. See the
+before all the coverage reports are uploaded. You can control the levels which
+are considered failing; the config above sets a loss of up to 5% as okay, and
+avoids patch coverage reporting a failure (otherwise, just changing a single
+uncovered line could cause a "failure" report on the PR). If you have 100%
+coverage, then you can remove the coverage failure settings, as you want any
+loss of coverage to fail. See the
 [docs](https://docs.codecov.com/docs/codecov-yaml) for all the options.
 
 <!-- ### Coverage for projects written in Python and C++

docs/pages/guides/docs.md

@@ -28,8 +28,21 @@ Ideally, software documentation should include:
 - **Explanations** to convey deeper understanding of why and how the software
   operates the way it does.
 
-This overall framework has a name, [Diátaxis][], and you can read more about it
-if you are interested.
+{: .note-title }
+
+> The Diátaxis framework
+>
+> This overall framework has a name, [Diátaxis][], and you can read more about
+> it if you are interested.
+
+<!-- [[[cog
+from cog_helpers import render_cookie
+with render_cookie() as package:
+    docs_conf_py = package.joinpath("docs/conf.py").read_text(encoding="utf-8").strip()
+    docs_index_md = package.joinpath("docs/index.md").read_text(encoding="utf-8").strip()
+    readthedocs_yaml = package.joinpath(".readthedocs.yml").read_text(encoding="utf-8").strip()
+]]] -->
+<!-- [[[end]]] -->
 
 ## Hand-written docs
 
@@ -40,15 +53,21 @@ is our recommended starting point for `conf.py`:
 
 ### conf.py
 
+<!-- prettier-ignore-start -->
+<!-- [[[cog
+print("```python")
+print(docs_conf_py)
+print("```")
+]]] -->
 ```python
 from __future__ import annotations
 
 import importlib.metadata
 
-project = "<package-name-here>"
-copyright = "2023, Your Name"
-author = "Your Name"
-version = release = importlib.metadata.version("<package-name-here>")
+project = "package"
+copyright = "2023, My Name"
+author = "My Name"
+version = release = importlib.metadata.version("package")
 
 extensions = [
     "myst_parser",
@@ -60,33 +79,35 @@ extensions = [
     "sphinx_copybutton",
 ]
 
-source_suffix = [".md", ".rst"]
+source_suffix = [".rst", ".md"]
 exclude_patterns = [
     "_build",
+    "**.ipynb_checkpoints",
     "Thumbs.db",
     ".DS_Store",
-    "**.ipynb_checkpoints",
     ".env",
     ".venv",
 ]
 
 html_theme = "furo"
 
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3", None),
-}
-
 myst_enable_extensions = [
     "colon_fence",
 ]
 
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
 nitpick_ignore = [
     ("py:class", "_io.StringIO"),
     ("py:class", "_io.BytesIO"),
 ]
 
 always_document_param_types = True
 ```
+<!-- [[[end]]] -->
+<!-- prettier-ignore-end -->
 
 We start by setting some configuration values, but most notably we are getting
 the package version from the installed version of your package. We are listing
@@ -132,12 +153,18 @@ docstrings, even if the parameter isn't documented yet. Feel free to check
 [sphinx-autodoc-typehints](https://github.com/tox-dev/sphinx-autodoc-typehints)
 for more options.
 
-## index.md
+### index.md
 
 Your `index.md` file can start out like this:
 
+<!-- prettier-ignore-start -->
+<!-- [[[cog
+print("````md")
+print(docs_index_md)
+print("````")
+]]] -->
 ````md
-# Project name
+# package
 
 ```{toctree}
 :maxdepth: 2
@@ -155,6 +182,8 @@ Your `index.md` file can start out like this:
 - {ref}`modindex`
 - {ref}`search`
 ````
+<!-- [[[end]]] -->
+<!-- prettier-ignore-end -->
 
 You can put your project name in as the title. The `toctree` directive houses
 your table of contents; you'll list each new page you add inside that directive.
@@ -191,6 +220,12 @@ plugins and try to build against an uninstalled version of your project.
 In order to use <https://readthedocs.org> to build, host, and preview your
 documentation, you must have a `.reathedocs.yml` file {% rr RTD100 %} like this:
 
+<!-- prettier-ignore-start -->
+<!-- [[[cog
+print("```yaml")
+print(readthedocs_yaml)
+print("```")
+]]] -->
 ```yaml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
@@ -201,7 +236,6 @@ build:
   os: ubuntu-22.04
   tools:
     python: "3.11"
-
 sphinx:
   configuration: docs/conf.py
 
@@ -212,6 +246,8 @@ python:
       extra_requirements:
         - docs
 ```
+<!-- [[[end]]] -->
+<!-- prettier-ignore-end -->
 
 This sets the readthedocs config version (2 is required) {% rr RTD101 %}.
 

docs/pages/guides/gha_pure.md

@@ -101,35 +101,30 @@ and then use `python -m build` or `pyproject-build`, but it's better to use
 `pipx` to install and run python applications. Pipx is provided by default by
 GitHub Actions (in fact, they use it to setup other applications).
 
-{% details Classic SDist builds %}
-
-If you don't have a pyproject.toml, you might need to use the raw `setup.py`
-commands. This is the classic way to do things, though you should consider
-direct usage of setup.py to be an implementation detail, and setup.py is not
-even required in modern packages.
-
-You must install SDist requirements by hand since `python setup.py sdist` does
-not get the benefits of having pip install things. If you have any special
-requirements in your `pyproject.toml` (and still don't want to use `build`),
-you'll need to list them. This is special just for the SDist, not for making
-wheels (which should be done by the PEP 517/518 process for you because you will
-use `build` or `pip`).
-
-To build the wheel, you can use `python -m pip wheel . -w wheelhouse`. Unlike
-build, this is a wheelhouse, not the output wheel; any wheels it makes during
-the process will be put here, not just the one you wanted to upload. Be sure to
-use something like `wheelhouse/my_package*.whl` when you pick your items from
-this folder so as not to pick a random dependency that didn't have a binary
-wheel already. Or just use PyPA/build.
-
-{% enddetails %}
-
 We upload the artifact just to make it available via the GitHub PR/Checks API.
 You can download a file to test locally if you want without making a release.
 
 We also add an optional check using twine for the metadata (it will be tested
 later in the upload action for the release job, as well).
 
+{: .highlight-title }
+
+> All-in-one action
+>
+> There is an
+> [all-in-one action](https://github.com/hynek/build-and-inspect-python-package)
+> that does all the work for you for a pure Python package, including extra
+> pre-upload checks & nice GitHub summaries.
+>
+> ```yaml
+> steps:
+>   - uses: actions/checkout@v3
+>   - uses: hynek/build-and-inspect-python-package@v1
+> ```
+>
+> The artifact it produces is named `Packages`, so that's what you need to use
+> later to publish.
+
 And then, you need a release job:
 
 {% tabs %} {% tab oidc Trusted Publishing %}
@@ -218,19 +213,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-
         with:
           fetch-depth: 0
 
-      - name: Build SDist and wheel
-        run: pipx run build
-
-      - uses: actions/upload-artifact@v3
-        with:
-          path: dist/*
-
-      - name: Check metadata
-        run: pipx run twine check dist/*
+      - uses: hynek/build-and-inspect-python-package@v1
 
   publish:
     needs: [dist]
@@ -272,19 +258,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-
         with:
           fetch-depth: 0
 
-      - name: Build SDist and wheel
-        run: pipx run build
-
-      - uses: actions/upload-artifact@v3
-        with:
-          path: dist/*
-
-      - name: Check metadata
-        run: pipx run twine check dist/*
+      - uses: hynek/build-and-inspect-python-package@v1
 
   publish:
     needs: [dist]
@@ -294,7 +271,7 @@ jobs:
     steps:
       - uses: actions/download-artifact@v3
         with:
-          name: artifact
+          name: Packages
           path: dist
 
       - uses: pypa/gh-action-pypi-publish@release/v1

docs/pages/guides/gha_wheels.md

@@ -227,10 +227,15 @@ multiple places, you can set `skip_existing` (but generally it's better to not
 try to upload the same file from two places - you can trick Travis into avoiding
 the sdist, for example).
 
+{: .note-title }
+
+> Other architectures
+>
 > On Travis, `cibuildwheel` even has the ability to create ARM and PowerPC
 > builds natively. IBM Z builds are also available but in beta. However, due to
 > Travis CI's recent dramatic reduction on open source support, emulating these
-> architectures on GHA or Azure is probably better.
+> architectures on GHA or Azure is probably better. Maybe look into Cirrus CI,
+> which has some harder-to-find architectures.
 
 <!-- prettier-ignore-start -->
 

docs/pages/guides/packaging_compiled.md

@@ -84,14 +84,14 @@ options in `tool.*` settings.
 <!-- [[[cog
 from cog_helpers import render_cookie
 with render_cookie(backend="skbuild") as skbuild:
-    skbuild_cmakelists_txt = skbuild.joinpath("CMakeLists.txt").read_text(encoding="utf-8")
-    skbuild_src_main_cpp = skbuild.joinpath("src/main.cpp").read_text(encoding="utf-8")
+    skbuild_cmakelists_txt = skbuild.joinpath("CMakeLists.txt").read_text(encoding="utf-8").strip()
+    skbuild_src_main_cpp = skbuild.joinpath("src/main.cpp").read_text(encoding="utf-8").strip()
 with render_cookie(backend="mesonpy") as mesonpy:
-    mesonpy_meson_build = mesonpy.joinpath("meson.build").read_text(encoding="utf-8")
-    mesonpy_src_main_cpp = mesonpy.joinpath("src/main.cpp").read_text(encoding="utf-8")
+    mesonpy_meson_build = mesonpy.joinpath("meson.build").read_text(encoding="utf-8").strip()
+    mesonpy_src_main_cpp = mesonpy.joinpath("src/main.cpp").read_text(encoding="utf-8").strip()
 with render_cookie(backend="maturin") as maturin:
-    maturin_cargo_toml = maturin.joinpath("Cargo.toml").read_text(encoding="utf-8")
-    maturin_src_lib_rs = maturin.joinpath("src/lib.rs").read_text(encoding="utf-8")
+    maturin_cargo_toml = maturin.joinpath("Cargo.toml").read_text(encoding="utf-8").strip()
+    maturin_src_lib_rs = maturin.joinpath("src/lib.rs").read_text(encoding="utf-8").strip()
 ]]] -->
 <!-- [[[end]]] -->
 
@@ -109,16 +109,13 @@ print("```")
 ]]] -->
 ```cmake
 cmake_minimum_required(VERSION 3.15...3.26)
-project(
-  ${SKBUILD_PROJECT_NAME}
-  VERSION ${SKBUILD_PROJECT_VERSION}
-  LANGUAGES CXX)
+project(${SKBUILD_PROJECT_NAME} LANGUAGES CXX)
 
+set(PYBIND11_FINDPYTHON ON)
 find_package(pybind11 CONFIG REQUIRED)
 
 pybind11_add_module(_core MODULE src/main.cpp)
 install(TARGETS _core DESTINATION ${SKBUILD_PROJECT_NAME})
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
@@ -168,7 +165,6 @@ py.extension_module('_core',
         'cpp_rtti=true',
     ]
 )
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
@@ -205,7 +201,6 @@ version = "0.18.1"
 # "extension-module" tells pyo3 we want to build an extension module (skips linking against libpython.so)
 # "abi3-py38" tells pyo3 (and maturin) to build using the stable ABI with minimum Python version 3.8
 features = ["extension-module", "abi3-py38"]
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
@@ -253,7 +248,6 @@ PYBIND11_MODULE(_core, m) {
       Some other explanation about the subtract function.
   )pbdoc");
 }
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
@@ -297,7 +291,6 @@ PYBIND11_MODULE(_core, m) {
       Some other explanation about the subtract function.
   )pbdoc");
 }
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->
@@ -334,7 +327,6 @@ fn _core(_py: Python, m: &PyModule) -> PyResult<()> {
 
     Ok(())
 }
-
 ```
 <!-- [[[end]]] -->
 <!-- prettier-ignore-end -->