diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd7831b90..ef6b6a7d9 100644 --- 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/conf.py b/conf.py index 63d1eb72d..131220831 100644 --- 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/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md index b6dbc4191..e3694d9fb 100644 --- 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 index dfa73b1ab..7a80bc048 100644 --- 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 index 0adad2a4f..408566762 100644 --- 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 index 02406cfd0..03bb8cdc2 100644 --- 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 index 8a45de302..d358a5582 100644 --- 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 index 2918a6ae1..bb6f51447 100644 --- 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 index a3ad1f2fc..c9a0125fa 100644 --- 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 index d23387c8a..c17b6e3ab 100644 --- 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 index d035e50e1..95afca937 100644 --- 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 index 6adb59256..aff17a419 100644 --- 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 index 9a9cfd3f4..4b3491876 100644 --- 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