This is a Sphinx extension that removes links from excessive references.
It also can be used as command-line linter to find or correct those references in .rst files.
Checks
Sphinx-linklint has two different checks:
self: find references that link to their own section. For example, in the description of a class, use :class: referring to itself. These should not be links since they will not take you someplace new.
paradup: find multiple identical references within a single paragraph. The first should be a link, but subsequent references don’t need to be links, they are just distractions.
Sphinx extension
To use linklint as a Sphinx extension, add it to the extensions list in your conf.py file:
extensions = [
# .. probably other extensions are already here..
"sphinx_linklint.ext",
]During the build process, linklint will run its checks and remove links from references it considers excessive. No changes are made to the source files.
Command-line use
You can use linklint as a command-line linter:
% sphinx-linklint --help usage: sphinx-linklint [-h] [--check CHECK] [--fix] files [files ...] positional arguments: files RST files to lint options: -h, --help show this help message and exit --check CHECK comma-separated checks to run (self, paradup, all) --fix Fix the issues in place
This can be useful to see what linklint considers excessive, or to modify .rst files to unlink excessive references. Where it can, linklint unlinks references by changing :func:`foo` to :func:`!foo`.
If you agree with linklint’s decisions, the Sphinx extension is a better option, since it doesn’t require changing the source files, and doesn’t hard-code the decisions.
Testing on CPython
To try local changes in the CPython docs:
cd python/cpython/Doc make clean venv html mv build build0 sed -i '' "/sphinx-linklint/s@.*@-e $HOME/linklint@" requirements.txt make clean venv uv pip install -r requirements.txt make html meld build0/html build/html # or diff -I 'Last updated on' -r build0/html build/html
Changes
v2.0.0 (2026-08-25)
Renamed to sphinx-linklint to clarify that this is a Sphinx extension and tool. Fixes issue 19.
Fix the sdist to include all files needed for the project, closing issue 21.
v1.0.3 (2026-08-25)
Publish an updated README under the old linklint name.
v1.0.1 (2026-06-09)
Fix: references that are fully qualified when they don’t need to be are now recognized and will be unlinked.
Fix: references to functions that incorrectly use the :meth: role are recognized by Sphinx anyway, so now linklint also recognizes and unlinks them. Fixes issue 13.
These fixes change the CPython docs build from 1579 self-references unlinked to 1649.
v1.0.0 (2026-05-02)
Fix: the :noindex: directive was ignored, so sections marked as such were considered targets when they shouldn’t have been. This is now fixed.
v0.4.1 (2026-03-27)
Linklint v0.4.0 required Sphinx 9.x, which prevented it from being used by the CPython docs. Now linklint will work with Sphinx 8.x as well.
v0.4.0 (2026-03-10)
A number of roles (:ref:, :doc: and others) were being unlinked when they seemed excessive, but shouldn’t have been. They are explicit references to other parts of the documentation, so should never be removed. This is now fixed.
v0.3.1 (2026-03-01)
Published to PyPI.
v0.3.0 (2026-02-28)
Methods are associated with classes properly in a number of ways.
The Sphinx extension now displays the number of references that were unlinked. The CPython docs report 3612 references unlinked.
v0.2.0 (2026-02-22)
Now available as a Sphinx extension. Instead of changing .rst source files, the excessive links are automatically unlinked in the generated documentation.
v0.1.0 (2026-02-21)
First version: works as a linter with --check and --fix to change .rst source files.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sphinx_linklint-2.0.0.tar.gz.
File metadata
- Download URL: sphinx_linklint-2.0.0.tar.gz
- Upload date:
- Size: 23.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e7ea4d3b1bd83665e9c2ab9fd92c6c645c805956d2e8ca6b0f528f3a9638910d
|
|
| MD5 |
1e105f6653ee6897b5e43e46b1454163
|
|
| BLAKE2b-256 |
f699f9947b30fd11e782855a13de1aac7d08634edba1c193a0ee01bf5338531c
|
Provenance
The following attestation bundles were made for sphinx_linklint-2.0.0.tar.gz:
Publisher:
publish.yml on nedbat/sphinx-linklint
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sphinx_linklint-2.0.0.tar.gz -
Subject digest:
e7ea4d3b1bd83665e9c2ab9fd92c6c645c805956d2e8ca6b0f528f3a9638910d - Sigstore transparency entry: 2583352696
- Sigstore integration time:
-
Permalink:
nedbat/sphinx-linklint@b5e3ee16464255993e7d70486eb476ff09694432 -
Branch / Tag:
refs/tags/2.0.0 - Owner: https://github.com/nedbat
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@b5e3ee16464255993e7d70486eb476ff09694432 -
Trigger Event:
push
-
Statement type:
File details
Details for the file sphinx_linklint-2.0.0-py3-none-any.whl.
File metadata
- Download URL: sphinx_linklint-2.0.0-py3-none-any.whl
- Upload date:
- Size: 13.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
12aa64f3b3faaa6e8a979a7d1f2c38617866652b670e3d19fa0f60a6ce3657ef
|
|
| MD5 |
8503b846f6731faae9c040f34ef587d2
|
|
| BLAKE2b-256 |
d73d6b96af48e139357e1e041a710d943c4bb79ad149c7aab074df784b4395ec
|
Provenance
The following attestation bundles were made for sphinx_linklint-2.0.0-py3-none-any.whl:
Publisher:
publish.yml on nedbat/sphinx-linklint
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sphinx_linklint-2.0.0-py3-none-any.whl -
Subject digest:
12aa64f3b3faaa6e8a979a7d1f2c38617866652b670e3d19fa0f60a6ce3657ef - Sigstore transparency entry: 2583352715
- Sigstore integration time:
-
Permalink:
nedbat/sphinx-linklint@b5e3ee16464255993e7d70486eb476ff09694432 -
Branch / Tag:
refs/tags/2.0.0 - Owner: https://github.com/nedbat
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@b5e3ee16464255993e7d70486eb476ff09694432 -
Trigger Event:
push
-
Statement type:
