linklint 0.3.1__tar.gz

linklint-0.3.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: linklint
+Version: 0.3.1
+Summary: A Sphinx extension to remove needless links
+Author-email: Ned Batchelder <ned@nedbatchelder.com>
+License-Expression: Apache-2.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+Requires-Dist: Sphinx
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: ty; extra == "dev"
+
+========
+Linklint
+========
+
+Linklint checks .rst files for excessive links to references.
+
+It also can be used as a Sphinx extension to automatically unlink references
+that should not be links.
+
+
+Checks
+======
+
+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:
+
+.. code:: python
+
+    extensions = [
+        # .. probably other extensions are already here..
+        "linklint.ext",
+    ]
+
+During the build process, linklint will run all its checks and unlink any
+reference it considers excessive.
+
+
+Command-line use
+================
+
+You can use linklint as a command-line linter::
+
+    % linklint --help
+    usage: 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.  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.
+
+
+Changes
+=======
+
+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.

linklint-0.3.1/README.rst

@@ -0,0 +1,93 @@
+========
+Linklint
+========
+
+Linklint checks .rst files for excessive links to references.
+
+It also can be used as a Sphinx extension to automatically unlink references
+that should not be links.
+
+
+Checks
+======
+
+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:
+
+.. code:: python
+
+    extensions = [
+        # .. probably other extensions are already here..
+        "linklint.ext",
+    ]
+
+During the build process, linklint will run all its checks and unlink any
+reference it considers excessive.
+
+
+Command-line use
+================
+
+You can use linklint as a command-line linter::
+
+    % linklint --help
+    usage: 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.  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.
+
+
+Changes
+=======
+
+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.

linklint-0.3.1/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "linklint"
+description = "A Sphinx extension to remove needless links"
+readme = "README.rst"
+authors = [
+    {name = "Ned Batchelder", email = "ned@nedbatchelder.com"},
+]
+license = "Apache-2.0"
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python",
+]
+
+requires-python = ">= 3.12"
+
+dependencies = [
+    "Sphinx",
+]
+
+dynamic = ["version"]
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "coverage",
+    "pytest",
+    "ruff",
+    "ty",
+]
+
+[project.scripts]
+linklint = "linklint.cli:main"
+
+[tool.setuptools.dynamic]
+version.attr = "linklint.__version__"
+
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+line-length = 100
+
+[tool.coverage.run]
+branch = true
+source = ["src", "tests"]
+
+[tool.coverage.report]
+exclude_also = [
+    "if __name__ == .__main__.:",
+    "pragma: only failure",
+    "pragma: debugging",
+    "if SAVE_INTERMEDIATE:",
+]

linklint-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

linklint-0.3.1/src/linklint/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.3.1"

linklint-0.3.1/src/linklint/cli.py

@@ -0,0 +1,64 @@
+import argparse
+import sys
+from pathlib import Path
+
+from linklint.linklint import CHECKS, LintIssue, lint_content
+from linklint.utils import plural
+
+
+def lint_file(filepath: str, fix: bool, checks: set[str]) -> list[LintIssue]:
+    """Lint a single RST file.
+
+    Returns a list of LintIssue objects.
+    """
+    # print(filepath)
+    path = Path(filepath)
+    content = path.read_text(encoding="utf-8")
+    result = lint_content(content, fix, checks)
+    if fix and result.fixed:
+        path.write_text(result.content, encoding="utf-8")
+    return result.issues
+
+
+def linklint(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--check",
+        help=f"comma-separated checks to run ({', '.join(CHECKS)}, all)",
+        default="all",
+    )
+    parser.add_argument("--fix", help="Fix the issues in place", action="store_true")
+    parser.add_argument("files", nargs="+", help="RST files to lint")
+    args = parser.parse_args(argv)
+
+    checks = set(args.check.split(","))
+    unknown = checks - set(CHECKS.keys()) - {"all"}
+    if unknown:
+        print(f"Unknown checks: {', '.join(unknown)}", file=sys.stderr)
+        return 2
+    if "all" in checks:
+        checks = set(CHECKS.keys())
+
+    issues = 0
+    fixed = 0
+    for filepath in args.files:
+        # This runs Sphinx on each file separately, which seems slow, but is
+        # faster than running it once on all the files.
+        for issue in lint_file(filepath, args.fix, checks):
+            fixed_suffix = ""
+            if issue.fixed:
+                fixed_suffix = " (fixed)"
+                fixed += 1
+            print(f"{filepath}:{issue.line}: {issue.message}{fixed_suffix}")
+            issues += 1
+
+    summary = f"Checked {plural(len(args.files), 'file')}, found {plural(issues, 'issue')}"
+    if args.fix:
+        summary += f", fixed {fixed}"
+    print(f"{summary}.")
+
+    return issues > 0
+
+
+def main():
+    sys.exit(linklint(sys.argv[1:]))

linklint-0.3.1/src/linklint/dump.py

@@ -0,0 +1,56 @@
+import sys
+from typing import TextIO
+
+from docutils import nodes
+
+
+INTERESTING_KEYS = [
+    "ids",
+    "names",
+    "reftype",
+    "reftarget",
+    "refuri",
+    "domain",
+    "objtype",
+    "desctype",
+    "class",
+    "fullname",
+    "module",
+]
+
+# INTERESTING_ATTRS = [
+#     "rawsource",
+# ]
+
+
+def dump_doctree(node: nodes.Node, fp: TextIO, indent: int = 0) -> None:  # pragma: debugging
+    """Print a nicely formatted tree of a docutils doctree."""
+    prefix = "    " * indent
+    if isinstance(node, nodes.Text):
+        text = node.astext()
+        print(f"{prefix}Text: {text!r}", file=fp)
+    else:
+        tag = node.__class__.__name__
+        attrs = []
+        for key in INTERESTING_KEYS:
+            if val := node.get(key):  # type: ignore
+                attrs.append(f"{key}={val!r}")
+        # for attr in INTERESTING_ATTRS:
+        #     if val := getattr(node, attr, None):
+        #         attrs.append(f".{attr}={val!r}")
+        attr_str = f" {{{', '.join(attrs)}}}" if attrs else ""
+        if tag == "reference":
+            print(vars(node), file=fp)
+        line = node.line
+        line_str = f" @{line}" if line else ""
+        print(f"{prefix}{tag}{attr_str}{line_str}", file=fp)
+        # print(f"{prefix}{node.attributes}", file=fp)
+        for child in node.children:
+            dump_doctree(child, fp, indent + 1)
+
+
+if __name__ == "__main__":
+    from linklint.linklint import parse_rst
+
+    with open(sys.argv[1]) as f:
+        dump_doctree(parse_rst(f.read()), sys.stdout)

linklint-0.3.1/src/linklint/ext.py

@@ -0,0 +1,60 @@
+from typing import cast
+
+from docutils import nodes
+from sphinx.application import Sphinx
+from sphinx.environment import BuildEnvironment
+from sphinx.util import logging
+from sphinx.util.typing import ExtensionMetadata
+
+import linklint
+from linklint.linklint import find_duplicate_refs, find_self_refs
+
+logger = logging.getLogger(__name__)
+
+
+def init_data(app: Sphinx) -> None:
+    app.env.linklint_counts: dict[str, int] = {}
+
+
+def process_reference_nodes(app, doctree):
+    """Find references that shouldn't be links, and un-reference them."""
+    # Change <reference><literal></reference> to just <literal>.
+
+    count = 0
+    for finder in (find_self_refs, find_duplicate_refs):
+        for ref in finder(doctree):
+            cast(nodes.Element, ref.parent).replace(ref, ref.children[0])
+            count += 1
+    app.env.linklint_counts[app.env.docname] = count
+
+
+def merge_data(
+    app: Sphinx,
+    env: BuildEnvironment,
+    docnames: list[str],
+    other: BuildEnvironment,
+) -> None:
+    # Env's start as copies of other envs, so we have to be careful to only
+    # merge data for the docnames that are actually being merged.
+    for docname in docnames:
+        if docname in other.linklint_counts:  # type: ignore
+            env.linklint_counts[docname] = other.linklint_counts[docname]  # type: ignore
+
+
+def display_results(app: Sphinx, exception: Exception | None) -> None:
+    if not exception:
+        total = sum(app.env.linklint_counts.values())  # type: ignore
+        logger.info(f"Linklint: unlinked {total} references")
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.connect("builder-inited", init_data)
+    app.connect("doctree-read", process_reference_nodes)
+    app.connect("env-merge-info", merge_data)
+    app.connect("build-finished", display_results)
+
+    return {
+        "version": linklint.__version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

linklint-0.3.1/src/linklint/linklint.py

@@ -0,0 +1,239 @@
+"""Linter to find link problems in RST files."""
+
+import collections
+import re
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Iterable
+
+from docutils import nodes
+from sphinx import addnodes
+
+from linklint.regions import Region, find_regions
+from linklint.rsthelp import parse_rst, resub_in_rst_line
+from linklint.utils import node_line_number, node_traceback
+
+
+class Resolver:
+    # Build a map from reference roles to object types.
+
+    # Dummy lambda's so that the object_types dict can be identical to the
+    # code in sphinx/sphinx/domains/python/__init__.py.
+    ObjType = lambda _, *refs: refs  # noqa: E731
+    _ = lambda s: 0  # noqa: E731
+
+    # object_types map from sphinx
+    # sphinx/sphinx/domains/python/__init__.py:725
+    object_types = {
+        "function": ObjType(_("function"), "func", "obj"),
+        "data": ObjType(_("data"), "data", "obj"),
+        "class": ObjType(_("class"), "class", "exc", "obj"),
+        "exception": ObjType(_("exception"), "exc", "class", "obj"),
+        "method": ObjType(_("method"), "meth", "obj"),
+        "classmethod": ObjType(_("class method"), "meth", "obj"),
+        "staticmethod": ObjType(_("static method"), "meth", "obj"),
+        "attribute": ObjType(_("attribute"), "attr", "obj"),
+        "property": ObjType(_("property"), "attr", "_prop", "obj"),
+        "type": ObjType(_("type alias"), "type", "class", "obj"),
+        "module": ObjType(_("module"), "mod", "obj"),
+    }
+
+    reftype_to_objtype = collections.defaultdict(list)
+    for objtype, names in object_types.items():
+        for name in names:
+            reftype_to_objtype[name].append(objtype)
+
+    def __init__(self, doctree: nodes.document) -> None:
+        self.region_map = {(r.kind, r.name): r for r in find_regions(doctree)}
+
+    def find_region(self, reftype: str, target: str) -> Region | None:
+        for objtype in self.reftype_to_objtype[reftype]:
+            region = self.region_map.get((objtype, target))
+            if region is not None:
+                return region
+        return None
+
+
+@dataclass
+class LintIssue:
+    line: int
+    message: str
+    fixed: bool = False
+
+
+@dataclass
+class LintWork:
+    doctree: nodes.document
+    content_lines: list[str]
+    fix: bool
+    fixed: bool
+
+
+CHECKS = {}
+
+
+def check(name: str):
+    """Decorator to register a lint check function."""
+
+    def decorator(func):
+        CHECKS[name] = func
+        return func
+
+    return decorator
+
+
+# pat/repl pairs for references styles.
+REF_FIXES = [
+    (
+        # :class:`MyClass` -> :class:`!MyClass`
+        r":{reftype}:`[~.]?{target}`",
+        r":{reftype}:`!{target}`",
+    ),
+    (
+        # :class:`Some Class <mymodule.MyClass>` -> :class:`!Some Class`
+        r":{reftype}:`([^<]+?)\s*<{target}>`",
+        r":{reftype}:`!\1`",
+    ),
+]
+
+
+@check("self")
+def check_self_links(work: LintWork) -> Iterable[LintIssue]:
+    for ref in find_self_refs(work.doctree):
+        line = node_line_number(ref)
+        reftype = ref.get("reftype")  # type: ignore
+        target = ref.get("reftarget")  # type: ignore
+        fixed = False
+        if work.fix:
+            for pat, repl in REF_FIXES:
+                fixed = resub_in_rst_line(
+                    lines=work.content_lines,
+                    line_num=line - 1,
+                    pat=pat.format(reftype=reftype, target=re.escape(target)),
+                    repl=repl.format(reftype=reftype, target=target),
+                    count=1,
+                )
+                if fixed:
+                    break
+            work.fixed |= fixed
+            if not fixed:
+                print(f"Line {line}: Couldn't fix self-link to :{reftype}:`{target}`")
+                print(f"Line was: {work.content_lines[line - 1]!r}")
+        yield LintIssue(line, f"self-link to :{reftype}:`{target}`", fixed=fixed)
+
+
+class RefFinder(nodes.SparseNodeVisitor):
+    """Visitor for nodes to track class context and find self-references."""
+
+    def __init__(self, doctree: nodes.document) -> None:
+        super().__init__(doctree)
+        self.resolver = Resolver(doctree)
+        self.self_refs: list[nodes.Node] = []
+        self.class_stack: list[str] = []
+        self.pushed_class: list[bool] = []
+
+    def visit_pending_xref(self, node: addnodes.pending_xref) -> None:
+        line = node_line_number(node)
+        reftype = node.get("reftype")
+        target = node.get("reftarget")
+
+        if reftype == "meth" and "." not in target:
+            if self.class_stack:
+                target = f"{self.class_stack[-1]}.{target}"
+            else:
+                # Method reference without class context: can't resolve, so skip.
+                target = None
+
+        if target:
+            region = self.resolver.find_region(reftype, target)
+            if region is not None and region.start <= line <= region.end_total:
+                self.self_refs.append(node)
+
+    def visit_desc(self, node: addnodes.desc) -> None:
+        objtype = node.get("objtype")
+        pushed = False
+        if objtype == "class":
+            self.class_stack.append(node.children[0].get("fullname"))
+            pushed = True
+        elif objtype == "method" and not self.class_stack:
+            self.class_stack.append(node.children[0].get("class"))
+            pushed = True
+        self.pushed_class.append(pushed)
+
+    def depart_desc(self, node: addnodes.desc) -> None:
+        if self.pushed_class.pop():
+            self.class_stack.pop()
+
+    # Have to explicitly pass on unknown nodes, and Python docs have a bunch.
+    def unknown_visit(self, node):  # pragma: no cover
+        pass
+
+    def unknown_departure(self, node):  # pragma: no cover
+        pass
+
+
+def find_self_refs(doctree: nodes.document) -> Iterable[nodes.Node]:
+    """Find references that point to the same region they are in."""
+
+    finder = RefFinder(doctree)
+    doctree.walkabout(finder)
+    return finder.self_refs
+
+
+@check("paradup")
+def check_duplicate_refs_in_paragraph(work: LintWork) -> Iterable[LintIssue]:
+    """Check references that appear more than once in the same paragraph."""
+    if work.fix:
+        raise Exception("Fixing is not available for --check=paradup")
+
+    for ref in find_duplicate_refs(work.doctree):
+        line = node_line_number(ref)
+        reftype = ref.get("reftype")  # type: ignore
+        target = ref.get("reftarget")  # type: ignore
+        yield LintIssue(line, f"duplicate :{reftype}:`{target}` in paragraph")
+
+
+def find_duplicate_refs(doctree: nodes.document) -> Iterable[nodes.Node]:
+    """Find references that appear more than once in the same paragraph."""
+    for para in doctree.findall(nodes.paragraph):
+        refs_by_target = defaultdict(list)
+        for ref in para.findall(addnodes.pending_xref):
+            reftype = ref.get("reftype")
+            target = ref.get("reftarget")
+            assert reftype and target, (
+                f"Reference missing reftype or target: {ref}\n{node_traceback(ref)}"
+            )
+            refs_by_target[(reftype, target)].append(ref)
+
+        for refs in refs_by_target.values():
+            if len(refs) > 1:
+                yield from refs[1:]
+
+
+@dataclass
+class LintResult:
+    content: str
+    issues: list[LintIssue]
+    fixed: bool
+
+
+def lint_content(content: str, fix: bool, checks: set[str]) -> LintResult:
+    doctree = parse_rst(content)
+    work = LintWork(
+        content_lines=content.splitlines(keepends=True),
+        doctree=doctree,
+        fix=fix,
+        fixed=False,
+    )
+
+    issues = []
+    for check_name in checks:
+        issues.extend(CHECKS[check_name](work))
+
+    result = LintResult(
+        content="".join(work.content_lines),
+        issues=issues,
+        fixed=work.fixed,
+    )
+
+    return result