From 6aca7ba7e3fcd2d0a568f0b88f22d1fb1e1de87a Mon Sep 17 00:00:00 2001 From: Catherine Date: Thu, 15 Feb 2024 19:35:21 +0000 Subject: [PATCH 1/2] docs: fix link rot. --- .github/workflows/main.yaml | 16 ++++++++++++++-- amaranth/lib/crc/__init__.py | 2 +- docs/.gitignore | 1 + docs/conf.py | 11 +++++++++++ docs/contrib.rst | 10 +++++----- docs/install.rst | 6 +++--- docs/intro.rst | 4 ++-- pyproject.toml | 1 + 8 files changed, 38 insertions(+), 13 deletions(-) diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index efb26efea..125e640ad 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -69,8 +69,6 @@ jobs: git fetch --tags https://github.com/amaranth-lang/amaranth.git - name: Set up PDM uses: pdm-project/setup-pdm@v4 - with: - python-version: '3.12' - name: Install dependencies run: | pdm install --dev @@ -83,6 +81,20 @@ 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 + - 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 diff --git a/amaranth/lib/crc/__init__.py b/amaranth/lib/crc/__init__.py index 241131298..8683c0955 100644 --- a/amaranth/lib/crc/__init__.py +++ b/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 diff --git a/docs/.gitignore b/docs/.gitignore index 69fa449dd..31d6a62c3 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1,2 @@ _build/ +_linkcheck/ diff --git a/docs/conf.py b/docs/conf.py index 573526fce..71b71d844 100644 --- a/docs/conf.py +++ b/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/[^/]+/[^/]+/$", +] diff --git a/docs/contrib.rst b/docs/contrib.rst index fcacf3cb8..691e84939 100644 --- a/docs/contrib.rst +++ b/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 `_ 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 `_ 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 `_. 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 `_. 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 diff --git a/docs/install.rst b/docs/install.rst index d92368084..3879eee99 100644 --- a/docs/install.rst +++ b/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| diff --git a/docs/intro.rst b/docs/intro.rst index 33ec2f27e..86f1aa3e3 100644 --- a/docs/intro.rst +++ b/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/ diff --git a/pyproject.toml b/pyproject.toml index ed58a0291..139a57002 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,6 +80,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" From 08a21f720b7ac208b0ebe3d16c05ae546d8e01bc Mon Sep 17 00:00:00 2001 From: Catherine Date: Thu, 15 Feb 2024 19:50:31 +0000 Subject: [PATCH 2/2] pyproject: suppress superfluous warning. --- .github/workflows/main.yaml | 4 ++++ pyproject.toml | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml index 125e640ad..34895cb8d 100644 --- a/.github/workflows/main.yaml +++ b/.github/workflows/main.yaml @@ -69,6 +69,8 @@ jobs: git fetch --tags https://github.com/amaranth-lang/amaranth.git - name: Set up PDM uses: pdm-project/setup-pdm@v4 + with: + python-version: '3.12' - name: Install dependencies run: | pdm install --dev @@ -88,6 +90,8 @@ jobs: 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 diff --git a/pyproject.toml b/pyproject.toml index 139a57002..972336c58 100644 --- a/pyproject.toml +++ b/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,