SF.net SVN: docutils:[9693 ] trunk/docutils/docutils/n odes.py

Revision: 9693
          http://sourceforge.net/p/docutils/code/9693
Author:   milde
Date:     2024-05-08 07:10:49 +0000 (Wed, 08 May 2024)
Log Message:
-----------
Doctree validation: Refactor element category classes.

Reconcile element category classes in `docutils.nodes` with descriptions
in doctree.txt and make them fit for use in declarations of valid
children.

- Define and use new class `SubRoot` for elements that may only be used as
  direct children of `document`.

- Drop `Structural` from base classes of `document`.

- Make `Invisible` a subclass of `Special`.
  Use this to simplify class definitions of `Invisible` special elements.

Sort categories

Modified Paths:
--------------
    trunk/docutils/docutils/nodes.py

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2024-05-08 07:10:43 UTC (rev 9692)
+++ trunk/docutils/docutils/nodes.py	2024-05-08 07:10:49 UTC (rev 9693)
@@ -1183,46 +1183,36 @@
     """Element at the root of a document tree."""
 
 
-class Titular:
-    """Headings (title, subtitle, rubric)."""
+class Structural:
+    """`Structural elements`__.
 
+    __ https://docutils.sourceforge.io/docs/ref/doctree.html
+       #structural-elements
+    """
 
-class PreBibliographic:
-    """Elements which may occur before Bibliographic Elements."""
 
+class SubRoot:
+    """Elements that may only be children of the root element."""
 
-class Invisible(PreBibliographic):
-    """Internal elements that don't appear in output."""
 
+class SubStructural(SubRoot):
+    """`Structural subelements`__ are children of structural elements.
 
-class Bibliographic:
-    """Bibliographic Elements (`docinfo` children)."""
+    Most Structural elements accept only some of the SubStructural elements.
 
-
-class Decorative(PreBibliographic):
-    """`Decorative elements`__ (`header` and `footer`).
-
     __ https://docutils.sourceforge.io/docs/ref/doctree.html
-       #decorative-elements
+       #structural-subelements
     """
 
 
-class Structural:
-    """`Structural Elements`__ that do not directly contain text data.
+class Bibliographic:
+    """`Bibliographic Elements`__ (displayed document meta-data).
 
     __ https://docutils.sourceforge.io/docs/ref/doctree.html
-       #structural-elements
+       #bibliographic-elements
     """
 
 
-class SubStructural:
-    """`Structural Subelements`__ are valid children of Structural Elements.
-
-    __ https://docutils.sourceforge.io/docs/ref/doctree.html
-       #structural-subelements
-    """
-
-
 class Body:
     """`Body elements`__.
 
@@ -1230,8 +1220,8 @@
     """
 
 
-class General(Body):
-    """Miscellaneous body elements."""
+class Admonition(Body):
+    """Admonitions (distinctive and self-contained notices)."""
 
 
 class Sequential(Body):
@@ -1238,8 +1228,8 @@
     """List-like body elements."""
 
 
-class Admonition(Body):
-    """Admonitions (distinctive and self-contained notices)."""
+class General(Body):
+    """Miscellaneous body elements."""
 
 
 class Special(Body):
@@ -1247,16 +1237,38 @@
 
 
 class Part:
-    """`Body Subelements`__.
+    """`Body Subelements`__ always occur within specific parent elements.
 
     __ https://docutils.sourceforge.io/docs/ref/doctree.html#body-subelements
     """
 
 
+class Decorative:
+    """Decorative elements (`header` and `footer`).
+
+    Children of `decoration`.
+    """
+
+
 class Inline:
-    """Inline elements."""
+    """Inline elements contain text data and possibly other inline elements.
+    """
 
 
+# Orthogonal categories
+
+class PreBibliographic:
+    """Elements which may occur before Bibliographic Elements."""
+
+
+class Invisible(Special, PreBibliographic):
+    """Internal elements that don't appear in output."""
+
+
+class Labeled:
+    """Contains a `label` as its first element."""
+
+
 class Referential(Resolvable):
     """Elements holding a cross-reference (outgoing hyperlink)."""
 
@@ -1267,13 +1279,16 @@
 
     indirect_reference_name = None
     """Holds the whitespace_normalized_name (contains mixed case) of a target.
-    Required for MoinMoin/reST compatibility."""
+    Required for MoinMoin/reST compatibility.
 
+    Provisional.
+    """
 
-class Labeled:
-    """Contains a `label` as its first element."""
 
+class Titular:
+    """Title, sub-title, or informal heading (rubric)."""
 
+
 class TextElement(Element):
     """
     An element which directly contains text.
@@ -1322,7 +1337,7 @@
 #  Root Element
 # ==============
 
-class document(Root, Structural, Element):
+class document(Root, Element):
     """
     The document root element.
 
@@ -1695,7 +1710,7 @@
 #  Meta-Data Element
 # ==================
 
-class meta(PreBibliographic, SubStructural, Element):
+class meta(PreBibliographic, SubRoot, Element):
     """Container for "invisible" bibliographic data, or meta-data."""
     valid_attributes = Element.valid_attributes + (
         'content', 'dir', 'http-equiv', 'lang', 'media', 'name', 'scheme')
@@ -1706,7 +1721,7 @@
 #  Bibliographic Elements
 # ========================
 
-class docinfo(SubStructural, Element):
+class docinfo(SubRoot, Element):
     """Container for displayed document meta-data."""
     valid_children = Bibliographic  # (%bibliographic.elements;)+
 
@@ -1733,7 +1748,7 @@
 #  Decorative Elements
 # =====================
 
-class decoration(PreBibliographic, SubStructural, Element):
+class decoration(PreBibliographic, SubRoot, Element):
     """Container for header and footer."""
 
     def get_header(self):
@@ -1889,14 +1904,14 @@
 class hint(Admonition, Element): pass
 class warning(Admonition, Element): pass
 class admonition(Admonition, Element): pass
-class comment(Special, Invisible, FixedTextElement): pass
+class comment(Invisible, FixedTextElement): pass
 
 
-class substitution_definition(Special, Invisible, TextElement):
+class substitution_definition(Invisible, TextElement):
     valid_attributes = Element.valid_attributes + ('ltrim', 'rtrim')
 
 
-class target(Special, Invisible, Inline, TextElement, Targetable):
+class target(Invisible, Inline, TextElement, Targetable):
     valid_attributes = Element.valid_attributes + (
         'anonymous', 'refid', 'refname', 'refuri')
 
@@ -1970,7 +1985,7 @@
                                       self['level'], Element.astext(self))
 
 
-class pending(Special, Invisible, Element):
+class pending(Invisible, Element):
     """
     Placeholder for pending operations.
 

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.