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.

git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@10225 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

docutils/RELEASE-NOTES.rst

@@ -217,6 +217,10 @@ Removals
 * Remove `parsers.rst.states.Struct` (obsoleted by `types.SimpleNamespace`)
   in Docutils 2.0.
 
+* Ignore the "match_titles" argument of
+  `parsers.rst.states.RSTState.nested_list_parse()` in Docutils 1.0;
+  remove it in Docutils 2.0.
+
 * Remove `frontend.OptionParser`, `frontend.Option`, `frontend.Values`,
   `frontend.store_multiple()`, and `frontend.read_config_file()` when
   migrating to argparse_ in Docutils 2.0 or later.

docutils/docutils/parsers/rst/directives/body.py

@@ -19,9 +19,8 @@ from docutils.utils.code_analyzer import Lexer, LexerError, NumberLines
 
 
 class BasePseudoSection(Directive):
+    """Base class for Topic and Sidebar."""
 
-    required_arguments = 1
-    optional_arguments = 0
     final_argument_whitespace = True
     option_spec = {'class': directives.class_option,
                    'name': directives.unchanged}
@@ -31,8 +30,8 @@ class BasePseudoSection(Directive):
     """Node class to be used (must be set in subclasses)."""
 
     def run(self):
-        if not (self.state_machine.match_titles
-                or isinstance(self.state_machine.node, nodes.sidebar)):
+        if not isinstance(self.state_machine.node,
+                          (nodes.document, nodes.section, nodes.sidebar)):
             raise self.error('The "%s" directive may not be used within '
                              'topics or body elements.' % self.name)
         self.assert_has_content()
@@ -64,15 +63,14 @@ class BasePseudoSection(Directive):
 
 class Topic(BasePseudoSection):
 
+    required_arguments = 1
     node_class = nodes.topic
 
 
 class Sidebar(BasePseudoSection):
 
-    node_class = nodes.sidebar
-
-    required_arguments = 0
     optional_arguments = 1
+    node_class = nodes.sidebar
     option_spec = BasePseudoSection.option_spec | {
                       'subtitle': directives.unchanged_required}
 

docutils/docutils/parsers/rst/directives/parts.py

@@ -43,8 +43,8 @@ class Contents(Directive):
                    'class': directives.class_option}
 
     def run(self):
-        if not (self.state_machine.match_titles
-                or isinstance(self.state_machine.node, nodes.sidebar)):
+        if not isinstance(self.state_machine.node,
+                          (nodes.document, nodes.section, nodes.sidebar)):
             raise self.error('The "%s" directive may not be used within '
                              'topics or body elements.' % self.name)
         document = self.state_machine.document

docutils/docutils/parsers/rst/states.py

@@ -108,6 +108,7 @@ import copy
 import re
 from types import FunctionType, MethodType
 from types import SimpleNamespace as Struct
+import warnings
 
 from docutils import nodes, statemachine, utils
 from docutils import ApplicationError, DataError
@@ -341,7 +342,7 @@ class RSTState(StateWS):
                           blank_finish,
                           blank_finish_state=None,
                           extra_settings={},
-                          match_titles=False,
+                          match_titles=False,  # deprecated, will be removed
                           state_machine_class=None,
                           state_machine_kwargs=None):
         """
@@ -355,6 +356,12 @@ class RSTState(StateWS):
         Return new offset and a boolean indicating whether there was a
         blank final line.
         """
+        if match_titles:
+            warnings.warn('The "match_titles" argument of '
+                          'parsers.rst.states.RSTState.nested_list_parse() '
+                          'will be ignored in Docutils 1.0 '
+                          'and removed in Docutils 2.0.',
+                          PendingDeprecationWarning, stacklevel=2)
         if state_machine_class is None:
             state_machine_class = self.nested_sm
         if state_machine_kwargs is None:
@@ -2435,8 +2442,7 @@ class Body(RSTState):
               self.state_machine.input_lines[offset:],
               input_offset=self.state_machine.abs_line_offset() + 1,
               node=self.parent, initial_state='Explicit',
-              blank_finish=blank_finish,
-              match_titles=self.state_machine.match_titles)
+              blank_finish=blank_finish)
         self.goto_line(newline_offset)
         if not blank_finish:
             self.parent += self.unindent_warning('Explicit markup')