Skip to content

chore: add link-checking command #551

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+54 −15
Open

chore: add link-checking command #551

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
47e7507
chore: add link-checking command
jameslamb Jul 12, 2025
8f1c47b
Merge branch 'main' into ci/add-linkchecking
jameslamb Jul 12, 2025
cae36ed
config changes
jameslamb Jul 12, 2025
1d8fff7
Merge branch 'ci/add-linkchecking' of github.com:jameslamb/python-pac…
jameslamb Jul 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion documentation/repository-files/readme-file-best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

```

Expand Down
2 changes: 1 addition & 1 deletion locales/es/LC_MESSAGES/documentation.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions locales/es/LC_MESSAGES/package-structure-code.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 "
Expand Down
4 changes: 2 additions & 2 deletions locales/es/LC_MESSAGES/tests.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 "
Expand Down
4 changes: 2 additions & 2 deletions locales/ja/LC_MESSAGES/documentation.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions locales/ja/LC_MESSAGES/package-structure-code.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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**) タグに依存します。"
Expand Down
4 changes: 2 additions & 2 deletions locales/ja/LC_MESSAGES/tests.po
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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` "
Expand Down
21 changes: 21 additions & 0 deletions noxfile.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]

Expand Down Expand Up @@ -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", ".")
Copy link
Preview

Copilot AI Jul 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider creating the LINKCHECK_OUTPUT_DIR before running Sphinx to avoid errors if the directory does not exist (e.g., LINKCHECK_OUTPUT_DIR.mkdir(parents=True, exist_ok=True)).

Suggested change
session.install("-e", ".")
session.install("-e", ".")
# Ensure LINKCHECK_OUTPUT_DIR exists
LINKCHECK_OUTPUT_DIR.mkdir(parents=True, exist_ok=True)

Copilot uses AI. Check for mistakes.

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):
"""
Expand Down
2 changes: 1 addition & 1 deletion package-structure-code/python-package-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tests/run-tests.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tutorials/add-readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading