|
| 1 | +from docutils import nodes |
| 2 | +from sphinx import addnodes |
| 3 | +from sphinx.application import Sphinx |
| 4 | +from sphinx.transforms.post_transforms import SphinxPostTransform |
| 5 | +from sphinx.util import logging |
| 6 | + |
| 7 | + |
| 8 | +logger = logging.getLogger(__name__) |
| 9 | + |
| 10 | + |
| 11 | +def is_public_internal_ref_target(target: str) -> bool: |
| 12 | + return target.startswith("idom.") and not target.rsplit(".", 1)[-1].startswith("_") |
| 13 | + |
| 14 | + |
| 15 | +class OnlyWarnOnBrokenInternalRefs(SphinxPostTransform): |
| 16 | + """ |
| 17 | + Warns about broken cross-reference links, but only for idom. |
| 18 | + This is very similar to the sphinx option ``nitpicky=True`` (see |
| 19 | + :py:class:`sphinx.transforms.post_transforms.ReferencesResolver`), but there |
| 20 | + is no way to restrict that option to a specific package. |
| 21 | + """ |
| 22 | + |
| 23 | + # this transform needs to happen before ReferencesResolver |
| 24 | + default_priority = 5 |
| 25 | + |
| 26 | + def run(self) -> None: |
| 27 | + for node in self.document.traverse(addnodes.pending_xref): |
| 28 | + target = node["reftarget"] |
| 29 | + |
| 30 | + if is_public_internal_ref_target(target): |
| 31 | + # let the domain try to resolve the reference |
| 32 | + found_ref = self.env.domains[node["refdomain"]].resolve_xref( |
| 33 | + self.env, |
| 34 | + node.get("refdoc", self.env.docname), |
| 35 | + self.app.builder, |
| 36 | + node["reftype"], |
| 37 | + target, |
| 38 | + node, |
| 39 | + nodes.TextElement("", ""), |
| 40 | + ) |
| 41 | + |
| 42 | + # warn if resolve_xref did not return or raised |
| 43 | + if not found_ref: |
| 44 | + logger.warning( |
| 45 | + f"API link {target} is broken.", location=node, type="ref" |
| 46 | + ) |
| 47 | + |
| 48 | + |
| 49 | +def setup(app: Sphinx) -> None: |
| 50 | + app.add_post_transform(OnlyWarnOnBrokenInternalRefs) |
0 commit comments