tests.test_docstrings module

Guard docstrings against a brace placeholder the MyST converter eats.

click_extra.sphinx.myst_docstrings rewrites MyST docstrings to reST at build time, and its cross-reference pattern reads a brace placeholder followed by a backtick as the opening of a role. A placeholder sitting against the closing backtick of an inline code span therefore opens a role instead of closing the span: the converter puts a role marker of the same name where the placeholder was, then swallows the prose up to the next backtick in the docstring. Both code-span boundaries move, and a sentence of documentation disappears into a literal.

Nothing reports it. What comes out is a well-formed role Sphinx has no opinion about, so the build stays warning-free and the corruption surfaces only to whoever reads the rendered page. That silence is what makes this worth a conformance test rather than a comment.

Doubling the backticks around the code span is the converter’s documented opt-out, and the fix every occurrence in the tree uses today.

A genuine role converts exactly the way an eaten placeholder does, so the two are told apart by name: a marker named in KNOWN_ROLES is a role this project may legitimately write, anything else is a placeholder that got eaten. The heuristic is deliberately precision-first, and blind by construction to a placeholder named after a real role. A missed occurrence costs one corrupted paragraph; a false positive would fail the suite on a legitimate cross-reference.

The check drives the real converter rather than a local copy of its pattern. A copy would report shapes the converter leaves alone: the conversion is a multi-pass pipeline that masks reST literals and protected spans before the cross-reference pattern ever sees the text, so the pattern on its own is not what decides the outcome. Calling upstream also means this test follows it instead of drifting from it.

Caution

That converter arrives with click-extra[sphinx], which only the docs dependency group pulls in, so the module skips wherever Sphinx is absent. Add Sphinx to the test group to turn this from a local check into a CI gate.

tests.test_docstrings.myst_to_rst(lines)

Convert a list of docstring lines from MyST to reST, in place.

Imported dynamically so a test environment without Sphinx skips this module instead of failing to collect the whole suite. exc_type has to widen to ImportError: click_extra.sphinx catches the missing Sphinx itself and re-raises a plain ImportError carrying an install hint, which the default ModuleNotFoundError would let through as a collection error.

Return type:

None

tests.test_docstrings.KNOWN_ROLES = frozenset({'abbr', 'attr', 'class', 'command', 'data', 'doc', 'download', 'envvar', 'exc', 'file', 'func', 'guilabel', 'kbd', 'keyword', 'manpage', 'meth', 'mod', 'obj', 'octicon', 'option', 'program', 'py', 'ref', 'samp', 'term'})

Role names a docstring may legitimately carry.

A converted marker named here is read as an intentional cross-reference. A placeholder unlucky enough to share one of these names is read the same way and passes unflagged, which is the price of never failing on a real role.

tests.test_docstrings.PLACEHOLDER_RE = re.compile('\\{([\\w-]+)\\}')

Match a brace placeholder, the shape the converter mistakes for a role.

tests.test_docstrings.test_package_discovered()

The scan actually walks the package, so a green result means something.

Return type:

None

tests.test_docstrings.test_detector_flags_eaten_placeholder()

The detector catches the corrupted span, and clears the safe shapes.

Return type:

None

tests.test_docstrings.test_no_mangled_docstrings(source_file)

No docstring loses a placeholder to the MyST-to-reST conversion.

Return type:

None