Docutils: Documentation Utilities Code

0.22.1rc1

Documentation amendments.

Announce removement of `memo.section_level` in Docutils 2.0.

Add some missing element descriptions to The Docutils Document Tree.

Revert section level changes in restructuredtext.rst doc. Move section
"Implicite Hyperlink Targets" to the end.

Mention Roles Defined in Standard Definition Files in
"reStructuredText Interpreted Text Roles".

Small editorial changes.

Add type info, shorten function call, merge repetitive commands.

Fix release date

rST parser: Use `section_level_offset` instead of `memo.section_level`.

Keeping record of the current section level in the state machine's "memo"
is cumbersome and error prone because it needs to be updated with every switch
of the current node.

Store the difference between the intended start level of nested parsing and the
number of parents of the base node in the new attribute `section_level_offset`.
Use it to correct the section level determined via `node.section_hierarchy()`.

rST parser: simplifications, fixes, and improvements

Define the attribute `parent_state_machine` only in
`parsers.rst.state.NestedStateMachine`.
It does not make sense in other state machines.

More detailled error message for inacessible section parents.

Test with a copy of Sphinx's `_fresh_title_style_context`.

Adjustments for nested_parse().

* Ensure valid output and update the "current node", if the base node is
the "current node".

If the base node is the state machine's "current node", we can safely assume
that it is attached to the document and check if sections are valid. We can
also update the "current node" of the parent state machine(s) after parsing.
This prevents invalid or mixed up document trees.

* Make the "current node" the default value for the "node" argument.
(This allows simple use for content included from external sources.)

* Restore `memo.section_level` after nested parsing into a custom node.
The calling code must ensure that section_level and current node stay in sync.

* Update unit tests.

rST parser: restore backwards compatibility of nested parsing.

* Keep document-wide title style hierarchy in nested parsing.

* Revert to using `document.memo.section_level` (required for nested parsing
into a detached base node with document-wide title styles).

+ simpler logic
+ backwards compatible
- more bookkeeping effort
- mandating a document-wide section title style hierarchy is ill-suited for
inclusion of rST blocks from external sources (e.g. extracted docstrings).
See `sphinx.util.parsing.nested_parse_to_nodes()` for an alternative.

This should restore compatibility with Sphinx's "only" directive broken by [r10204].

Deprecate the "match_titles" argument of `states.RSTState.nested_list_parse()`.

`nested_list_parse()` is intended for second and subsequent items of lists
and list-like constructs, it does never match section titles.

The argument value was (mis)used in directive classes to check wheter a
`<topic>` or `<sidebar>` element can be returned.
This check is now replaced by testing for a valid parent node.

More distict variable name in parsers.rst.states.RSTState.nested_list_parse().

The `RSTState.nested_parse()` method creates/uses a new state machine
that differs from the class instance's `self.state_machine`
(which may be the master state machine or another nested state machine).
Rename the local variable holding the new machine from `state_machine`
to `my_state_machine`.