Citation-Safe Docstrings

A helper that wires a documentation build to keep repeated citations unique and remove broken backreferences when turning NumPy-style docstrings into doctrees.

Capabilities

Deduplicate citation labels

• Building docs for two objects that both cite the same label yields unique citation targets per object while the in-text links still resolve. @test
• Rebuilding the same docs produces stable citation labels for the same objects instead of churn between runs. @test

Clean invalid backreferences

• After citation handling runs, stray backreference nodes that point to missing targets are removed so doctree validation passes. @test

Event wiring

• Citation relabeling and backreference cleanup are registered during Sphinx setup so autodoc and doctree-read processing happen without manual calls in tests. @test

Implementation

@generates

API

from typing import Mapping, Sequence
from sphinx.application import Sphinx
from docutils.nodes import document

def configure_citation_handling(app: Sphinx) -> None:
    """
    Register the handlers on the Sphinx app to deduplicate citations and clean backreferences during the build.
    """

def build_processed_doctrees(app: Sphinx, docstrings: Mapping[str, str]) -> Sequence[document]:
    """
    Create doctrees for the provided objects (mapping from object name to docstring),
    ensuring citation labels are unique per object and backreferences are cleaned.
    """

Dependencies { .dependencies }

numpydoc { .dependency }

Provides docstring-to-doctree processing with citation relabeling and backreference cleanup needed by this helper.