Merge branch 'main' into main

flpm · web-flow · commit c869eb5a15e7 · 2025-07-18T09:14:43.000-04:00
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -960,7 +960,19 @@
       "profile": "https://github.com/hfactor13",
       "contributions": [
         "code",
-        "review"
+        "review",
+        "design"
+      ]
+    },
+    {
+      "login": "jameslamb",
+      "name": "James Lamb",
+      "avatar_url": "https://avatars.githubusercontent.com/u/7608904?v=4",
+      "profile": "https://github.com/jameslamb",
+      "contributions": [
+        "code",
+        "doc",
+        "translation"
       ]
     }
   ],
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -188,6 +188,12 @@ There are different sessions in nox related to building the docs: `docs`, `docs-
     ```
     To see the guide built locally, open the file `_build/html/index.html` in your browser.
 
+- `docs-linkcheck`: this session checks that links in documentation work
+    ```bash
+    nox -e docs-linkcheck
+    ```
+    If the tests fail, you will see logs in the terminal and in `_build/linkcheck_output/output.txt`.
+
 - `docs-test`: this session runs the tests for the guide.
     ```bash
     nox -e docs-test
diff --git a/README.md b/README.md
diff --git a/_ext/translation_graph.py b/_ext/translation_graph.py
@@ -146,6 +146,8 @@ def run(self):
         fig.update_layout(
             paper_bgcolor="rgba(0,0,0,0)",
             plot_bgcolor="rgba(0,0,0,0)",
+            hoverlabel_bgcolor="var(--bs-body-bg)",
+            hoverlabel_font_color="var(--bs-body-color)",
             font_color="var(--bs-body-color)",
             margin=dict(l=40, r=40, t=40, b=40),
             xaxis_showgrid=False,
diff --git a/_static/pyos.css b/_static/pyos.css
@@ -1,6 +1,6 @@
 /* PyOS-specific vars :) */
 :root {
-  --pyos-color-primary: #703c87;
+  --pyos-color-primary: #cfafde;
   --pyos-color-secondary: #8045e5;
   --pyos-color-secondary-highlight: #591bc2;
   --pyos-color-tertiary: #a66c98;
diff --git a/conf.py b/conf.py
@@ -206,6 +206,18 @@
 # myst complains about bibtex footnotes because of render order
 suppress_warnings = ["myst.footnote"]
 
+# -- Options for linkcheck -------------------------------------------------
+
+# config reference: https://www.sphinx-doc.org/en/master/usage/configuration.html
+linkcheck_anchors_ignore_for_url = [
+    # GitHub code links with line-number anchors are reported as "not found"
+    r"https:\/\/.*github\.com.*\/blob\/.*",
+]
+
+linkcheck_ignore = [
+    # gnu.org is so strictly rate-limited that retries to it really slow down link-checking... just assume they're fine
+    r"https:\/\/.*gnu\.org.*",
+]
 
 def _post_build(app: "Sphinx", exception: Exception | None) -> None:
     rss.generate_tutorials_feed(app)
diff --git a/documentation/repository-files/license-files.md b/documentation/repository-files/license-files.md
@@ -130,13 +130,42 @@ This would not be true with a GPL licensed package. `GPL-3` packages can include
 
 ## What about software citation?
 
-While many permissive licenses do not require citation we STRONG 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). We will cover this topic when we talk about creating DOI's for your package using Zenodo.
+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).
 
-<!-- TODO: add link when lesson is created - but also we don't yet know how citation.cff files work with Zenodo (do they work??) will the citation info update with a new Zenodo link
+### Citation.cff files: Making your software citable
 
-These files - we need to understand if that date releases auto populates or forces zenodo to modify it's citation. If it's not dynamic it could be problematic
+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.
 
--->
+#### What citation.cff files add to your repository
+
+When you add a `CITATION.cff` file to your repository, GitHub automatically detects it and displays a "Cite this repository" button. This makes it easy for users to properly cite your software. The file contains standardized citation information that tools and services can automatically read and use. GitHub will generate both APA and BibTeX citation formats for users.
+
+#### How dates are tracked in citation.cff files
+
+The citation file tracks important dates for your software. The `date-released` field shows when the current version was released. The `date-published` field shows when the software was first made available. You also include a `version` field with the specific version number.
+
+You should update these dates with each new release so people cite the correct version of your software.
+
+#### Integration with Zenodo
+
+Citation.cff files work well with Zenodo, which is a popular place to store research software and get DOIs. When you create a Zenodo release, it can automatically pull information from your citation file. This keeps your citation information the same between GitHub and Zenodo. You can also include your Zenodo DOI in the citation file. Each time you make a new GitHub release, it can create a new Zenodo version with updated citation information.
+
+
+Here's a basic example of what a `CITATION.cff` file might look like:
+
+```yaml
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+authors:
+  - family-names: "Your Last Name"
+    given-names: "Your First Name"
+    orcid: "https://orcid.org/0000-0000-0000-0000"
+title: "Your Package Name"
+version: 1.0.0
+doi: "10.5281/zenodo.1234"
+date-released: 2025-07-12
+url: "https://github.com/yourusername/your-package"
+```
 
 # References
 
diff --git a/documentation/repository-files/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md
@@ -84,7 +84,7 @@ Example: [![PyPI version shields.io](https://img.shields.io/pypi/v/pandera.svg)]
 ```{tip}
 Once you package is accepted to pyOpenSci, we will provide you with
 a badge to add to your repository that shows that it has been reviewed.
-[![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/12)
+[![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/12)
 
 ```
 
diff --git a/locales/es/LC_MESSAGES/documentation.po b/locales/es/LC_MESSAGES/documentation.po
@@ -1941,7 +1941,7 @@ msgid ""
 "Once you package is accepted to pyOpenSci, we will provide you with a "
 "badge to add to your repository that shows that it has been reviewed. "
 "[![pyOpenSci](https://pyopensci.org/badges/peer-"
-"reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/12)"
+"reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/12)"
 msgstr ""
 
 #: ../../documentation/repository-files/readme-file-best-practices.md:85
diff --git a/locales/es/LC_MESSAGES/package-structure-code.po b/locales/es/LC_MESSAGES/package-structure-code.po
@@ -7199,13 +7199,13 @@ msgstr "Herramienta 3: versionado de setuptools-scm usando etiquetas git"
 
 #: ../../package-structure-code/python-package-versions.md:226
 msgid ""
-"[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an "
+"[`Setuptools_scm`](https://github.com/pypa/setuptools-scm/) is an "
 "extension that you can use with setuptools to manage package versions. "
 "**Setuptools_scm** operates the same way that **hatch_vcs** (discussed "
 "above) does. It stores a version in a **\\_version.py** file and relies "
 "on (**git**) tags to determine the package's current version."
 msgstr ""
-"[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) es una "
+"[`Setuptools_scm`](https://github.com/pypa/setuptools-scm/) es una "
 "extensión que puede usar con setuptools para gestionar las versiones de "
 "los paquetes. **Setuptools_scm** opera de la misma manera que "
 "**hatch_vcs** (discutido anteriormente). Almacena una versión en un "
diff --git a/locales/es/LC_MESSAGES/tests.po b/locales/es/LC_MESSAGES/tests.po
@@ -654,14 +654,14 @@ msgstr ""
 
 #: ../../tests/run-tests.md:127
 msgid ""
-"**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end "
+"**[Hatch](https://github.com/pypa/hatch)** is a modern end-to-end "
 "packaging tool that works with the popular build backend called "
 "hatchling. `hatch` offers a `tox`-like setup where you can run tests "
 "locally using different Python versions. If you are using `hatch` to "
 "support your packaging workflow, you may want to also use its testing "
 "capabilities rather than using `nox`."
 msgstr ""
-"**[Hatch](https://github.com/ofek/hatch)** es una herramienta de "
+"**[Hatch](https://github.com/pypa/hatch)** es una herramienta de "
 "empaquetado moderna de extremo a extremo que funciona con el popular "
 "backend de construcción llamado hatchling. `hatch` ofrece una "
 "configuración similar a `tox` donde puedes ejecutar pruebas localmente "
diff --git a/locales/ja/LC_MESSAGES/documentation.po b/locales/ja/LC_MESSAGES/documentation.po
@@ -2122,11 +2122,11 @@ msgid ""
 "Once you package is accepted to pyOpenSci, we will provide you with a "
 "badge to add to your repository that shows that it has been reviewed. "
 "[![pyOpenSci](https://pyopensci.org/badges/peer-"
-"reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/12)"
+"reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/12)"
 msgstr ""
 "あなたのパッケージがpyOpenSciに受理されると、あなたのリポジトリにレビュー済みであることを示すバッジを提供します。 "
 "[![pyOpenSci](https://pyopensci.org/badges/peer-"
-"reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/12)"
+"reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/12)"
 
 #: ../../documentation/repository-files/readme-file-best-practices.md:85
 msgid "pyOpenSci"
diff --git a/locales/ja/LC_MESSAGES/package-structure-code.po b/locales/ja/LC_MESSAGES/package-structure-code.po
@@ -6146,13 +6146,13 @@ msgstr "ツール3: gitタグを使ったsetuptools-scmのバージョン管理"
 
 #: ../../package-structure-code/python-package-versions.md:226
 msgid ""
-"[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an "
+"[`Setuptools_scm`](https://github.com/pypa/setuptools-scm/) is an "
 "extension that you can use with setuptools to manage package versions. "
 "**Setuptools_scm** operates the same way that **hatch_vcs** (discussed "
 "above) does. It stores a version in a **\\_version.py** file and relies "
 "on (**git**) tags to determine the package's current version."
 msgstr ""
-"[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) "
+"[`Setuptools_scm`](https://github.com/pypa/setuptools-scm/) "
 "は、パッケージのバージョンを管理するために setuptools と一緒に使うことができる拡張機能です。 "
 "**Setuptools_scm**は、**hatch_vcs**（前述）と同じように動作します。 バージョンを **_version.py** "
 "ファイルに保存し、パッケージの現在のバージョンを決定するために (**git**) タグに依存します。"
diff --git a/locales/ja/LC_MESSAGES/tests.po b/locales/ja/LC_MESSAGES/tests.po
@@ -619,14 +619,14 @@ msgstr ""
 
 #: ../../tests/run-tests.md:127
 msgid ""
-"**[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end "
+"**[Hatch](https://github.com/pypa/hatch)** is a modern end-to-end "
 "packaging tool that works with the popular build backend called "
 "hatchling. `hatch` offers a `tox`-like setup where you can run tests "
 "locally using different Python versions. If you are using `hatch` to "
 "support your packaging workflow, you may want to also use its testing "
 "capabilities rather than using `nox`."
 msgstr ""
-"**[Hatch](https://github.com/ofek/hatch)** "
+"**[Hatch](https://github.com/pypa/hatch)** "
 "は、hatchlingと呼ばれる人気のあるビルドバックエンドで動作する最新のエンドツーエンドパッケージングツールです。  `hatch` は "
 "`tox` のようなセットアップを提供し、異なる Python バージョンを使ってローカルでテストを実行することができます。 "
 "パッケージングのワークフローをサポートするために `hatch` を使っているのであれば、 `nox` を使うよりも `hatch` "
diff --git a/noxfile.py b/noxfile.py
@@ -31,6 +31,11 @@
 # Sphinx parameters used to build the guide
 BUILD_PARAMETERS = ["-b", "html"]
 
+# Sphinx parameters used when checking that links work
+# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
+LINKCHECK_PARAMETERS = ["-b", "linkcheck", "-Dlinkcheck_timeout=5", "-Dlinkcheck_rate_limit_timeout=30", "--fail-on-warning"]
+LINKCHECK_OUTPUT_DIR = pathlib.Path(BUILD_DIR, "linkcheck_output")
+
 # Sphinx parameters used to test the build of the guide
 TEST_PARAMETERS = ["--keep-going", "-E", "-a"]
 
@@ -70,6 +75,22 @@ def docs(session):
     session.notify("build-release-languages", session.posargs)
 
 
+@nox.session(name="docs-linkcheck")
+def docs_linkcheck(session):
+    """
+    Check that links are well-formed and point to something that exists.
+    """
+    session.install("-e", ".")
+    session.run(
+        SPHINX_BUILD,
+        *LINKCHECK_PARAMETERS,
+        SOURCE_DIR,
+        LINKCHECK_OUTPUT_DIR,
+        *session.posargs,
+        env={"SPHINX_ENV": "development"},
+    )
+
+
 @nox.session(name="docs-test")
 def docs_test(session):
     """
diff --git a/package-structure-code/python-package-versions.md b/package-structure-code/python-package-versions.md
@@ -223,7 +223,7 @@ If you use **setuptools_scm**, then you might find **hatch_vcs** and **hatchling
 
 ### Tool 3: setuptools-scm versioning using git tags
 
-[`Setuptools_scm`](https://github.com/pypa/setuptools_scm/) is an
+[`Setuptools_scm`](https://github.com/pypa/setuptools-scm/) is an
 extension that you can use with setuptools to manage package
 versions. **Setuptools_scm** operates the same way that
 **hatch_vcs** (discussed above) does. It stores a version in a **\_version.py** file and relies on (**git**) tags to
diff --git a/tests/run-tests.md b/tests/run-tests.md
@@ -124,7 +124,7 @@ We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a Python
 
 - **[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an automation tool that supports common steps such as building documentation, running tests across various versions of Python, and more.
 
-- **[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end packaging tool that works with the popular build backend called hatchling. `hatch` offers a `tox`-like setup where you can run tests locally using different Python versions. If you are using `hatch` to support your packaging workflow, you may want to also use its testing capabilities rather than using `nox`.
+- **[Hatch](https://github.com/pypa/hatch)** is a modern end-to-end packaging tool that works with the popular build backend called hatchling. `hatch` offers a `tox`-like setup where you can run tests locally using different Python versions. If you are using `hatch` to support your packaging workflow, you may want to also use its testing capabilities rather than using `nox`.
 
 * [**make:**](https://www.gnu.org/software/make/manual/make.html) Some developers use Make, which is a build automation tool, for running tests
 due to its versatility; it's not tied to a specific language and can be used
diff --git a/tutorials/add-readme.md b/tutorials/add-readme.md
@@ -193,7 +193,7 @@ Your finished `README.md` file should look something like this:
 # pyosPackage
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8365068.svg)](https://doi.org/10.5281/zenodo.8365068)
-[![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/115)
+[![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/115)
 
 ## What pyosPackage does
 
