Docutils: Documentation Utilities Code

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].

Downgrade "duplicate ID" message from "serious" to "error".

A duplicate ID is not a critical error where the output will
inevitably contain severe errors but rather "a major issue that should
adressed. If ignored, the output will contain unpredictable errors."
(cf. :PEP:`0258` Error Handling).

Re-use `nodes.document.set_id()` in the XML parser, but
only for registering an existing ID, do not generate IDs.

"include" directive: handle duplicate names and IDs in sub-documents

When the :parser: option is specified, the included file is parsed
into a dummy `<document>` and children are appended.
Let internal bookkeeping attributes reference the main document
equivalents, so that element names and IDs share a namespace
with the including document.