Docutils: Documentation Utilities Code

test manpage warning on image content

Catch deliberate system messages when running the test suite.

When we know a test case triggers a system message,
make sure that it does not clutter the output.

System messages that are only printed to the warning stream may
be checked in an `assertRaisesRegex()` block after setting the "halt_level"
configuration setting to a matching level (cf. e.g. "test_nodes.py"
or the "test/*/test_*_misc.py" test modules).

Trim down overhead of type hints.

get_(reader|parser|writer)class():
Don't use @overload for individual values of the same type that return
a class that is a subclass of a well defined abstract base class.

docutils.nodes:
There is no need to add a TypeVar for the type of a default value when
the alternative is any ``Any | _DefaultT``.

Cf. patches #212.

Small fixes and additions.

Be more specific in FAQ answer.

Don't list minor fix (bug #287) in HISTORY.

Shorten some docstrings to adhere to documentation policy
(multi-line docstrings should be summary line, blank line, details).

Better name for function factory that returns a keyword validating function.
(cf. https://stackoverflow.com/questions/3368830/how-to-name-factory-like-methods).

Fix attribute name mismatch "autonum" -> "auto".

Explain F401 noqa comment.

Fix typo in "writers/html5_polyglot/minimal.css" stylesheet.

Avoid confusing variable name ``twidth`` in latex writer.

move manpage image TODO into test_writers/test_manpage

ODT writer: Fix handling of `*.xml` stylesheets.

According to the ODT writer documentation, the "stylesheet" setting
should work with either "styles.odt" or "styles.xml" files.

Fix errors with "*.xml" style files [bugs:#494].
Thanks to Paul Kishimoto for report and analysis.

image enhancement

Document, that type hints use Python 3.10 syntax.

Allow transient elements `<target>` and `<pending>` before a figure `<caption>`.

In rST, the "figure" directive's content must start with a paragraph (that
becomes the caption) or an empty comment (to get a legend without caption).

The change allows passing a "classes" or "names" attribute value to the
figure caption via the "class" directive rsp. an internal hyperlink target.

Change the `references.PropagateTargets` transform to remove a `<target>`
element followed by a `<caption>` (after propagating ids and names)
to keep the doctree valid.

Fix the HTML5 writer, to apply the attributes to the `<figcaption>` element,
(instead of the included `<p>`).

Fix LaTeX writer to handle "classes" and "ids" attributes of a `<caption>`
element.

Add test cases.
Remove misleading test case. Figures without caption are invalid and won't get
a "Figure 1."-style caption with the Docutils writers.

Add internal source and line attributes to more nodes.

The rST parser now also adds internal source and line attributes to
`<compound>`, `<container>`, `<sidebar>`, `<topic>`, `<line_block>`,
and `<line>` nodes.

Based on a pull request by Rob Taylor (on the github mirror) but adding
source and line info instead of the "raw" line number to account for
source parts included with the "include" directive,
also fixing line blocks (both directive and via line-block syntax),
and adding a test case.

See also [feature-requests:#41].