epythet.validation.detectors

Named doctree detectors, referenced from ledger rules by detector.function.

Each detector takes a ParsedDocstring and returns a list of evidence strings, one per hit (an empty list means the rule does not fire). They read the docutils doctree rather than rendered HTML so that the rules keep working under any Sphinx theme, and under a MkDocs backend, exactly as decided in D8.

The detectors are the measured prototype from the validation research (detect2.py and refine.py), ported one to one; the refinements that took false positives from 2/14 to 1/14 on the control set are marked inline.

Module Attributes

DETECTORS	Registry filled by detector(); the ledger loader validates against it.
NAPOLEON_SECTIONS	Section names napoleon recognises (Google style), lower-cased.
NEAR_SECTIONS	Common misspellings / near-misses of section names that napoleon ignores.

Functions

blockquote_with_unexpected_indent(parsed)	A block quote and an Unexpected indentation message: stray indent (DR016).
collapsed_table(parsed)	A simple-table border in the source with no table node in the tree (DR019).
detector(name)	Register a detector under name (the name used in rule YAML).
directive_content_lost(parsed)	A directive is written in the source but produced no content node (DR018).
markdown_fence_literal(parsed)	A Markdown fence collapsed into an inline literal (DR006).
mixed_bullet_markers(parsed)	Two adjacent sibling bullet lists: the marker character changed mid-list (DR022).
near_miss_section_term(parsed)	A definition-list term that is a misspelt section name (DR013).
param_definition_list(parsed)	A top-level definition list of single-word terms: probably a parameter list (DR017).
problematic_nodes(parsed)	Unbalanced inline markup: every problematic node in the tree (DR010).
prose_definition_term(parsed)	A definition-list term of three or more words: prose eaten by indentation (DR014).
section_as_definition_list(parsed)	A Google section (Args:) became a definition-list term: napoleon is off (DR012).
system_messages(parsed)	Every message docutils reported while parsing the docstring (DR032).
title_references(parsed)	Single backticks parsed as a title reference, i.e. italics not code (DR011).

epythet.validation.detectors.DETECTORS: dict[str, Detector] = {'blockquote_with_unexpected_indent': <function blockquote_with_unexpected_indent>, 'collapsed_table': <function collapsed_table>, 'directive_content_lost': <function directive_content_lost>, 'markdown_fence_literal': <function markdown_fence_literal>, 'mixed_bullet_markers': <function mixed_bullet_markers>, 'near_miss_section_term': <function near_miss_section_term>, 'param_definition_list': <function param_definition_list>, 'problematic_nodes': <function problematic_nodes>, 'prose_definition_term': <function prose_definition_term>, 'section_as_definition_list': <function section_as_definition_list>, 'system_messages': <function system_messages>, 'title_references': <function title_references>}

Registry filled by detector(); the ledger loader validates against it.

epythet.validation.detectors.NAPOLEON_SECTIONS = frozenset({'args', 'arguments', 'attention', 'attributes', 'caution', 'danger', 'error', 'example', 'examples', 'hint', 'important', 'keyword args', 'keyword arguments', 'methods', 'note', 'notes', 'other parameters', 'parameters', 'raise', 'raises', 'receive', 'receives', 'references', 'return', 'returns', 'see also', 'tip', 'todo', 'warning', 'warnings', 'warns', 'yield', 'yields'})

Section names napoleon recognises (Google style), lower-cased.

epythet.validation.detectors.NEAR_SECTIONS = frozenset({'arg', 'argument', 'attribute', 'exception', 'exceptions', 'exemple', 'exemples', 'kwarg', 'kwargs', 'param', 'parameter', 'params', 'rasies', 'retruns', 'returnss', 'yeilds'})

Common misspellings / near-misses of section names that napoleon ignores.

epythet.validation.detectors.blockquote_with_unexpected_indent(parsed)

A block quote and an Unexpected indentation message: stray indent (DR016).

The message gate is what makes this reliable; a block quote alone is how a legitimate quotation is written (research §3.3).

Return type:

list[str]

epythet.validation.detectors.collapsed_table(parsed)

A simple-table border in the source with no table node in the tree (DR019).

Refinement from the research: the border line must contain two or more whitespace-separated runs of =, otherwise a section underline matches.

Return type:

list[str]

epythet.validation.detectors.detector(name)

Register a detector under name (the name used in rule YAML).

Return type:

Callable[[Callable[[ParsedDocstring], list[str]]], Callable[[ParsedDocstring], list[str]]]

epythet.validation.detectors.directive_content_lost(parsed)

A directive is written in the source but produced no content node (DR018).

With stub directives registered, an unknown directive name (.. codeblock::) or a body that docutils rejected leaves only a system message behind; the content the author wrote is gone from the page.

Return type:

list[str]

epythet.validation.detectors.markdown_fence_literal(parsed)

A Markdown fence collapsed into an inline literal (DR006).

Refinement from the research: a triple-backtick fence parses as an inline literal whose text starts or ends with a backtick, because two of the fence characters are consumed as the literal’s delimiters. Testing for three backticks in the paragraph text does not work.

Return type:

list[str]

epythet.validation.detectors.mixed_bullet_markers(parsed)

Two adjacent sibling bullet lists: the marker character changed mid-list (DR022).

Return type:

list[str]

epythet.validation.detectors.near_miss_section_term(parsed)

A definition-list term that is a misspelt section name (DR013).

Return type:

list[str]

epythet.validation.detectors.param_definition_list(parsed)

A top-level definition list of single-word terms: probably a parameter list (DR017).

Return type:

list[str]

epythet.validation.detectors.problematic_nodes(parsed)

Unbalanced inline markup: every problematic node in the tree (DR010).

Return type:

list[str]

epythet.validation.detectors.prose_definition_term(parsed)

A definition-list term of three or more words: prose eaten by indentation (DR014).

Return type:

list[str]

epythet.validation.detectors.section_as_definition_list(parsed)

A Google section (Args:) became a definition-list term: napoleon is off (DR012).

Return type:

list[str]

epythet.validation.detectors.system_messages(parsed)

Every message docutils reported while parsing the docstring (DR032).

Return type:

list[str]

epythet.validation.detectors.title_references(parsed)

Single backticks parsed as a title reference, i.e. italics not code (DR011).

Return type:

list[str]