Merge branch 'main' into main

Author: willingc

.github/workflows/build-book.yml

@@ -10,12 +10,18 @@ on:
     branches:
       - main
 
-# This job installs dependencies, build the book, and pushes it to `gh-pages`
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Build and test the book, then deploy from a separate job.
 jobs:
   build-test-book:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch_depth: 0
 
@@ -25,7 +31,7 @@ jobs:
           git restore-mtime
 
       - name: Setup Python
-        uses: actions/setup-python@v6
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: "3.13"
 
@@ -38,7 +44,7 @@ jobs:
         run: echo "::set-output name=dir::$(pip cache dir)"
 
       - name: Cache dependencies
-        uses: actions/cache@v5
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae #v5.0.5
         with:
           path: ${{ steps.pip-cache.outputs.dir }}
           key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
@@ -50,6 +56,9 @@ jobs:
 
       - name: Build book
         run: nox -s docs-test
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d #v6
 
       # Save html as artifact
       - name: Save book html as artifact for viewing
@@ -59,20 +68,30 @@ jobs:
           path: |
             _build/html/
 
-      # Push the book's HTML to github-pages
-      - name: Push to GitHub Pages
-        # Only push if on main branch
-        if: github.ref == 'refs/heads/main'
-        uses: peaceiris/actions-gh-pages@v4.0.0
+      - name: Upload artifact
+        # Automatically uploads an artifact from the './_site' directory by default
+        uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b #v4
         with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./_build/html
+          path: ./_build/html
 
       # Test for bad links and ensure alt tags for usability
       - name: Check HTML using htmlproofer
+        continue-on-error: true
         uses: chabad360/htmlproofer@master
         with:
           directory: "_build/html"
           arguments: |
             --ignore-files "/.+\/_static\/.+/,/genindex.html/"
-            --ignore-status-codes "0, 200, 403, 429, 503"
+            --ignore-status-codes "0, 200, 401, 403, 429, 503"
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build-test-book
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 #v5.0.0

.pre-commit-config.yaml

@@ -25,7 +25,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         additional_dependencies:
@@ -36,7 +36,7 @@ repos:
           )$
 
   - repo: https://github.com/errata-ai/vale
-    rev: v3.13.1
+    rev: v3.14.1
     hooks:
       - id: vale
 

README.md

@@ -24,7 +24,6 @@ Initiatives.
 
 ## Contributing statement
 
-
 ## How to setup
 
 This repository contains the source files for the [pyOpenSci Python packaging guide](https://pyopensci.org/python-package-guide).
@@ -44,44 +43,49 @@ To build, follow these steps:
 1. Install `nox`
 
    ```console
-   $ python -m pip install nox
+   python -m pip install nox
    ```
+
 2. Build the documentation:
 
    ```console
-   $ nox -s docs
+   nox -s docs
    ```
 
 This should create a local environment in a `.nox` folder, build the documentation (as specified in the `noxfile.py` configuration), and the output will be in `_build/html`.
 
 To build live documentation that updates when you update local files, run the following command:
 
 ```console
-$ nox -s docs-live
+nox -s docs-live
 ```
 
+If you are a uv user, you can also skip installing `nox` and use `uvx` instead:
+
+`uvx nox -s docs-live`
+
 ### Building for release
 
 When building for release, the docs are built multiple times for each translation,
 but translations are only included in the production version of the guide after some completion threshold.
 
 The sphinx build environment is controlled by an environment variable `SPHINX_ENV`
 
-- when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
+* when `SPHINX_ENV=development` (default), sphinx assumes all languages are built,
   and includes them in the language selector
-- when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
+* when `SPHINX_ENV=production`, only those languages in `release_languages` (set in `conf.py`)
   are built and included in the language selector.
 
 Most of the time you should not need to set `SPHINX_ENV`,
 as it is forced by the primary nox sessions intended to be used for release or development:
 
 `SPHINX_ENV=development`
-- `docs-live` - autobuild english
-- `docs-live-lang` - autobuild a single language
-- `docs-live-langs` - autobuild all languages
+* `docs-live` - autobuild english
+* `docs-live-lang` - autobuild a single language
+* `docs-live-langs` - autobuild all languages
 
 `SPHINX_ENV=production`
-- `build-test` - build all languages for production
+* `build-test` - build all languages for production
 
 ## Contributing to this guide
 

_static/pyos.css

@@ -340,21 +340,21 @@ See https://github.com/pydata/pydata-sphinx-theme/pull/1784
   src: url("./fonts/poppins-v20-latin-600.woff2") format("woff2"); /* Chrome 36+, Opera 23+, Firefox 39+, Safari 12+, iOS 10+ */
 }
 
-/* nunitosans-regular - latin */
+/* nunitosans-variable - latin */
 @font-face {
   font-display: swap;
   font-family: "NunitoSans";
   font-style: normal;
-  font-weight: 400;
+  font-weight: 200 800;
   src: url("./fonts/NunitoSans-VariableFont.woff2") format("woff2");
 }
 
-/* nunitosans-italic - latin */
+/* nunitosans-italic-variable - latin */
 @font-face {
   font-display: swap;
   font-family: "NunitoSans";
   font-style: italic;
-  font-weight: 400;
+  font-weight: 200 800;
   src: url("./fonts/NunitoSans-Italic-VariableFont.woff2") format("woff2");
 }
 

conf.py

@@ -176,6 +176,12 @@
     ".pytest_cache/README.md",
     "vale-styles/*",
     "CODE_OF_CONDUCT.md",
+    "CLAUDE.md",
+    # Local virtualenv under the doc root; otherwise Sphinx/Myst scans site-packages.
+    ".venv",
+    "venv",
+    "env",
+    "LICENSE.rst"
 ]
 
 # For sitemap generation

documentation/repository-files/license-files.md

@@ -132,6 +132,13 @@ This would not be true with a GPL licensed package. `GPL-3` packages can include
 
 While many permissive licenses do not require citation, we strongly encourage that you cite all software that you use in papers, blogs, and other publications. You tell your users how to cite your package by using a [citation.cff file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files).
 
+:::{tip} Additional resources on software citation
+The Turing Way has excellent guides on this topic:
+
+- [CITATION.cff files](https://book.the-turing-way.org/communication/citable/citable-cff) — detailed guide on creating and maintaining citation files
+- [Software citation pathways](https://book.the-turing-way.org/pathways/pathways-software-citation) — overview of how software citation works in practice
+:::
+
 ### Citation.cff files: Making your software citable
 
 A `CITATION.cff` file is a machine-readable file that provides citation information for your software package. The "cff" stands for "Citation File Format," which is a standardized format for software citation metadata.

examples/pure-hatch/.github/workflows/release.yml

@@ -28,7 +28,7 @@ jobs:
           hatch --version # Verify that Hatch is installed
       - name: Build artifacts
         run: hatch build
-      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           path: dist/
           name: dist.zip
@@ -50,4 +50,4 @@ jobs:
         with:
           name: dist.zip
           path: dist/
-      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # v1.13.0
+      - uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0

index.md

@@ -17,7 +17,7 @@ We support the Python tools that scientists need to create open science workflow
 
 ```{only} html
 ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pyopensci/python-package-guide?color=purple&display_name=tag&style=plastic)
-[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/contributing-guide)
+[![](https://img.shields.io/github/stars/pyopensci/python-package-guide?style=social)](https://github.com/pyopensci/python-package-guide)
 [![DOI](https://zenodo.org/badge/556814582.svg)](https://zenodo.org/badge/latestdoi/556814582)
 ```
 
@@ -56,7 +56,7 @@ Community docs
 Publish your docs
 ```
 
-##  Tutorial Series: Create a Python Package
+## Tutorial Series: Create a Python Package
 
 The first round of our community-developed, how to create a Python package tutorial series for scientists is complete! Join our community review process or watch development of future tutorials in our [GitHub repo here](https://github.com/pyOpenSci/python-package-guide).
 
@@ -91,6 +91,7 @@ The first round of our community-developed, how to create a Python package tutor
 :class-card: left-aligned
 
 * [Introduction to Hatch](/tutorials/get-to-know-hatch)
+* [Run Python scripts using Hatch](/tutorials/run-python-scripts-hatch)
 
 :::
 ::::
@@ -193,7 +194,6 @@ Learn about best practices for:
 
 ## Tests
 
-
 :::::{grid} 1 1 2 2
 :class-container: text-center
 :gutter: 3
@@ -212,7 +212,8 @@ Learn about best practices for:
 :::{card} ✨ Run your tests ✨
 :class-card: left-aligned
 
-* [Run tests locally](tests/run-tests)
+* [Run tests locally with Hatch](tests/run-tests)
+* [Run tests with nox](tests/run-tests-nox)
 * [Run tests in CI](tests/tests-ci)
 :::
 ::::
@@ -245,7 +246,7 @@ contribute.
 
 :::::
 
-:::{image} https://www.pyopensci.org/images/people-building-blocks.jpg
+:::{image} <https://www.pyopensci.org/images/people-building-blocks.jpg>
 :align: right
 :width: 350
 :alt: xkcd comic showing a stick figure on the ground and one in the air. The one on the ground is saying. `You're flying! how?`  The person in the air replies  `Python!` Below is a 3 rectangle comic with the following text in each box. Box 1 - I learned it last night. Everything is so simple. Hello world is just print hello world. Box 2 - the person on the ground says - come join us programming is fun again. It's a whole new world. But how are you flying? box 3 - the person flying says - i just typed import antigravity. I also sampled everything in the medicine cabinet. But i think this is the python. The person on the ground is saying - that's it?

package-structure-code/intro.md

@@ -2,7 +2,7 @@
 
 This section covers everything you need to structure your Python package, configure metadata, choose build tools, and publish your package to PyPI and conda-forge.
 
-:::::{grid} 1 2
+:::::{grid} 1 1 2 2
 :gutter: 3
 
 ::::{grid-item}

package-structure-code/python-package-structure.md

@@ -39,7 +39,7 @@ Want to learn how to create the structure to build your package? Click here.
 
 An example of the **src/package** layout structure is below.
 
-```{console}
+```bash
 myPackageRepoName
 ├── CHANGELOG.md               ┐
 ├── CODE_OF_CONDUCT.md         │