Fix link rot in docs

.github/workflows/main.yaml

@@ -83,6 +83,22 @@ jobs:
           name: docs
           path: docs/_build
 
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out source code
+        uses: actions/checkout@v4
+      - name: Set up PDM
+        uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          pdm install --dev
+      - name: Check links in documentation
+        run: |
+          pdm run document-linkcheck
+
   required: # group all required workflows into one to avoid reconfiguring this in Actions settings
     needs:
       - test

amaranth/lib/crc/__init__.py

@@ -54,7 +54,7 @@ class Algorithm:
       form of polynomial but remove the leading '1'.
 
     .. _reveng: https://reveng.sourceforge.io/crc-catalogue/all.htm
-    .. _crcmod: http://crcmod.sourceforge.net/crcmod.predefined.html
+    .. _crcmod: https://crcmod.sourceforge.net/crcmod.predefined.html
     .. _CRC Zoo: https://users.ece.cmu.edu/~koopman/crc/
 
     Many commonly used CRC algorithms are available in the

docs/.gitignore

@@ -1 +1,2 @@
 _build/
+_linkcheck/

docs/conf.py

@@ -50,3 +50,14 @@
 .. role:: py(code)
    :language: python
 """
+
+linkcheck_ignore = [
+    r"^http://127\.0\.0\.1:8000$"
+]
+
+linkcheck_anchors_ignore_for_url = [
+    r"^https://matrix\.to/",
+    r"^https://web\.libera\.chat/",
+    # React page with README content included as a JSON payload.
+    r"^https://github\.com/[^/]+/[^/]+/$",
+]

docs/contrib.rst

@@ -9,9 +9,9 @@ Filing problem reports
 
 We would like Amaranth to be a best-in-class design tool, and hearing about issues people encounter while using it is crucial for improving it. While we do care a lot about correctness of the results, we care about the experience of using the tool just as much. Amaranth is meant to be a tool that is comfortable to use: with fewer sharp edges (no matter how much technological appeal they might have) and more signs and guardrails.
 
-Please `report <issues>`_ any problems you encounter using Amaranth. To go beyond that: **If, while you are using Amaranth, you see an error message that is hard to understand or is misleading, please report it as a bug. Even (especially!) if you think you did something wrong.**
+Please `report <issues_>`_ any problems you encounter using Amaranth. To go beyond that: **If, while you are using Amaranth, you see an error message that is hard to understand or is misleading, please report it as a bug. Even (especially!) if you think you did something wrong.**
 
-.. _issues: https://github.com/amaranth-lang/amaranth
+.. _issues: https://github.com/amaranth-lang/amaranth/issues
 
 When filing problem reports, please include the following information:
 
@@ -34,7 +34,7 @@ Proposing new features
 
 Amaranth is a programming language and a toolchain, which is different from many other kinds of open source projects in that just about every part of it is, unavoidably, tightly coupled to every other one, the result being that seemingly obvious and apparently minor decisions can have dramatic consequences years later.
 
-To make sure that new features undergo the scrutiny necessary for commitment to many years of support, and to make sure that everyone in the community who will be impacted by the changes has a chance to make their voice heard, **all substantial changes, including feature proposals, must go through a formal Request for Comments process**. The process, as well as the accepted proposals, are described `here <rfcs>`_. Typically, substantial changes are accepted after one to several rounds of community review achieve near-unanimous consensus.
+To make sure that new features undergo the scrutiny necessary for commitment to many years of support, and to make sure that everyone in the community who will be impacted by the changes has a chance to make their voice heard, **all substantial changes, including feature proposals, must go through a formal Request for Comments process**. The process, as well as the accepted proposals, are described `here <rfcs_>`_. Typically, substantial changes are accepted after one to several rounds of community review achieve near-unanimous consensus.
 
 .. _rfcs: https://amaranth-lang.org/rfcs/
 
@@ -48,8 +48,8 @@ Preparing the environment
 
 The Amaranth codebase uses the PDM_ package and dependency manager to structure the development workflow. Please `install PDM`_ first and make sure you have downloaded the latest changes to the source files. Once you have done so, run:
 
-.. _PDM: https://pdm.fming.dev/
-.. _install PDM: https://pdm.fming.dev/latest/#recommended-installation-method
+.. _PDM: https://pdm-project.org/
+.. _install PDM: https://pdm-project.org/latest/#recommended-installation-method
 
 .. code-block:: console
 

docs/install.rst

@@ -18,10 +18,10 @@ Synthesizing, placing and routing an Amaranth design for an FPGA requires the FP
 
 .. _CPython: https://www.python.org/
 .. _PyPy3.8: https://www.pypy.org/
-.. _pip: https://pip.pypa.io/
+.. _pip: https://pip.pypa.io/en/stable/
 .. _Yosys: https://yosyshq.net/yosys/
 .. _PyPI: https://pypi.org/
-.. _GTKWave: http://gtkwave.sourceforge.net/
+.. _GTKWave: https://gtkwave.sourceforge.net/
 
 
 .. _install-deps:
@@ -109,7 +109,7 @@ Installing prerequisites
 
       If Yosys |yosys-version| is not available, `build Yosys from source`_.
 
-      .. _build Yosys from source: https://github.com/YosysHQ/yosys/#setup
+      .. _build Yosys from source: https://github.com/YosysHQ/yosys/#building-from-source
 
       |upgrade-pip|
 

docs/intro.rst

@@ -57,8 +57,8 @@ The Amaranth simulator is event-driven and can simulate designs with multiple cl
 
 Although Amaranth does not support native code simulation or co-simulation at the moment, such support will be added in near future.
 
-.. _Icarus Verilog: http://iverilog.icarus.com/
-.. _Verilator: https://www.veripool.org/wiki/verilator
+.. _Icarus Verilog: https://steveicarus.github.io/iverilog/
+.. _Verilator: https://www.veripool.org/verilator/
 .. _GTKWave: http://gtkwave.sourceforge.net/
 .. _PyPy: https://www.pypy.org/
 

pyproject.toml

@@ -39,6 +39,10 @@ amaranth-rpc = "amaranth.rpc:main"
 requires = ["pdm-backend"]
 build-backend = "pdm.backend"
 
+[tool.pdm]
+# Remove this once we no longer support Python 3.8.
+ignore_package_warnings = ["sphinx*"]
+
 [tool.pdm.build]
 # If amaranth 0.3 is checked out with git (e.g. as a part of a persistent editable install or
 # a git worktree cached by tools like poetry), it can have an empty `nmigen` directory left over,
@@ -80,6 +84,7 @@ test-docs.cmd = "sphinx-build -b doctest docs/ docs/_build"
 
 document.cmd = "sphinx-build docs/ docs/_build/"
 document-live.cmd = "sphinx-autobuild docs/ docs/_build/ --watch amaranth"
+document-linkcheck.cmd = "sphinx-build docs/ docs/_linkcheck/ -b linkcheck"
 
 coverage-text.cmd = "python -m coverage report"
 coverage-html.cmd = "python -m coverage html"