chore: add link-checking command (#551)

* chore: add link-checking command

* config changes

---------

Co-authored-by: Tetsuo Koyama <[email protected]>

Author: jameslamb

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

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)

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)
 
 ```
 

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

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 "

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 "

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"

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**) タグに依存します。"

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` "

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):
     """