Make component's "TransformSpec" interface optional.

`Transformer.populate_from_components()` now ignores components
not inheriting `docutils.TransformSpec`.
This is a prerequisite to allow use of standard I/O classes in the Publisher.

Document the handling of `unknown_reference_resolvers`.
Use PEP 257 "Docstring Conventions".

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

3 files changed, 65 insertions, 45 deletions

diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt
index ec86c50a9..12b7511db 100644
--- a/docutils/HISTORY.txt
+++ b/docutils/HISTORY.txt
@@ -19,10 +19,6 @@ Changes Since 0.19
   - Declared support for Python 3.11 in setup.py and tox.ini.
     Patch by Hugo van Kemenade.
 
-* tox.ini
-
-  - Extracted flake8 configuration and moved to ``.flake8``.
-
 * docutils/core.py
 
   - Added new ``publish_bytes()`` function to explicitly return
@@ -35,12 +31,6 @@ Changes Since 0.19
   - Deprecated returning ``bytes`` from ``StringOutput.encode()``.
     Users should use the new class ``BytesOutput`` instead.
 
-* setup.py
-
-  - Fix: SetuptoolsDeprecationWarning: Installing '' as data is deprecated,
-
-    by adding data directories to package_data.packages list.
-
 * docutils/languages/
   docutils/parsers/rst/languages/
 
@@ -55,6 +45,11 @@ Changes Since 0.19
 
   - Improved mock Sphinx module.
 
+* docutils/transforms/__init__.py
+
+  - `Transformer.populate_from_components()` now silently ignores
+    components that are not instances of `docutils.TransformSpec`.
+
 * docutils/utils/__init__.py
 
   - New utility function ``xml_declaration()``.
@@ -90,6 +85,15 @@ Changes Since 0.19
 
   - Do not output empty "manual" in ``.TH``
 
+* setup.py
+
+  - Fix SetuptoolsDeprecationWarning: "Installing '' as data is deprecated"
+    by adding data directories to package_data.packages list.
+
+* tox.ini
+
+  - Extracted flake8 configuration and moved to ``.flake8``.
+
 * test/
 
   - Refactored tests in to use common ``unittest`` idioms.
diff --git a/docutils/docutils/__init__.py b/docutils/docutils/__init__.py
index 524d1b883..3052208e7 100644
--- a/docutils/docutils/__init__.py
+++ b/docutils/docutils/__init__.py
@@ -217,11 +217,13 @@ class SettingsSpec:
 
 
 class TransformSpec:
-
     """
     Runtime transform specification base class.
 
-    TransformSpec subclass objects used by `docutils.transforms.Transformer`.
+    Provides the interface to register "transforms" and helper functions
+    to resolve references with a `docutils.transforms.Transformer`.
+
+    https://docutils.sourceforge.io/docs/ref/transforms.html
     """
 
     def get_transforms(self):
@@ -239,11 +241,13 @@ class TransformSpec:
     default_transforms = ()
 
     unknown_reference_resolvers = ()
-    """List of functions to try to resolve unknown references.  Unknown
-    references have a 'refname' attribute which doesn't correspond to any
-    target in the document.  Called when the transforms in
-    `docutils.transforms.references` are unable to find a correct target.  The
-    list should contain functions which will try to resolve unknown
+    """List of functions to try to resolve unknown references.
+
+    Unknown references have a 'refname' attribute which doesn't correspond
+    to any target in the document.  Called when the transforms in
+    `docutils.transforms.references` are unable to find a correct target.
+
+    The list should contain functions which will try to resolve unknown
     references, with the following signature::
 
         def reference_resolver(node):
@@ -260,7 +264,10 @@ class TransformSpec:
 
         reference_resolver.priority = 100
 
-    Override in subclasses."""
+    This hook is provided for 3rd party extensions.
+    Example use case: the `MoinMoin - ReStructured Text Parser`
+    in ``sandbox/mmgilbe/rst.py``.
+    """
 
 
 class Component(SettingsSpec, TransformSpec):
diff --git a/docutils/docutils/transforms/__init__.py b/docutils/docutils/transforms/__init__.py
index 982cd5e5b..de6fdee58 100644
--- a/docutils/docutils/transforms/__init__.py
+++ b/docutils/docutils/transforms/__init__.py
@@ -32,10 +32,7 @@ class TransformError(ApplicationError):
 
 
 class Transform:
-
-    """
-    Docutils transform component abstract base class.
-    """
+    """Docutils transform component abstract base class."""
 
     default_priority = None
     """Numerical priority of this transform, 0 through 999 (override)."""
@@ -63,10 +60,16 @@ class Transform:
 
 
 class Transformer(TransformSpec):
-
     """
-    Stores transforms (`Transform` classes) and applies them to document
-    trees.  Also keeps track of components by component type name.
+    Store "transforms" and apply them to the document tree.
+
+    Collect lists of `Transform` instances and "unknown_reference_resolvers"
+    from Docutils components (`TransformSpec` instances).
+    Apply collected "transforms" to the document tree.
+
+    Also keeps track of components by component type name.
+
+    https://docutils.sourceforge.io/docs/peps/pep-0258.html#transformer
     """
 
     def __init__(self, document):
@@ -76,7 +79,7 @@ class Transformer(TransformSpec):
         """
 
         self.unknown_reference_resolvers = []
-        """List of hook functions which assist in resolving references"""
+        """List of hook functions which assist in resolving references."""
 
         self.document = document
         """The `nodes.document` object this Transformer is attached to."""
@@ -84,12 +87,14 @@ class Transformer(TransformSpec):
         self.applied = []
         """Transforms already applied, in order."""
 
-        self.sorted = 0
+        self.sorted = False
         """Boolean: is `self.tranforms` sorted?"""
 
         self.components = {}
-        """Mapping of component type name to component object.  Set by
-        `self.populate_from_components()`."""
+        """Mapping of component type name to component object.
+
+        Set by `self.populate_from_components()`.
+        """
 
         self.serialno = 0
         """Internal serial number to keep track of the add order of
@@ -139,24 +144,28 @@ class Transformer(TransformSpec):
 
     def populate_from_components(self, components):
         """
-        Store each component's default transforms, with default priorities.
+        Store each component's default transforms and reference resolvers
+
+        Transforms are stored with default priorities for later sorting.
+        "Unknown reference resolvers" are sorted and stored.
+        Components that don't inherit from `TransformSpec` are ignored.
+
         Also, store components by type name in a mapping for later lookup.
         """
+        resolvers = []
         for component in components:
-            if component is None:
+            if not isinstance(component, TransformSpec):
                 continue
             self.add_transforms(component.get_transforms())
             self.components[component.component_type] = component
-        self.sorted = 0
-        # Set up all of the reference resolvers for this transformer. Each
-        # component of this transformer is able to register its own helper
-        # functions to help resolve references.
-        unknown_reference_resolvers = []
-        for i in components:
-            unknown_reference_resolvers.extend(i.unknown_reference_resolvers)
-        decorated_list = sorted((f.priority, f)
-                                for f in unknown_reference_resolvers)
-        self.unknown_reference_resolvers.extend(f[1] for f in decorated_list)
+            resolvers.extend(component.unknown_reference_resolvers)
+        self.sorted = False  # sort transform list in self.apply_transforms()
+
+        # Sort and add helper functions to help resolve unknown references.
+        def keyfun(f):
+            return f.priority
+        resolvers.sort(key=keyfun)
+        self.unknown_reference_resolvers += resolvers
 
     def apply_transforms(self):
         """Apply all of the stored transforms, in priority order."""
@@ -164,10 +173,10 @@ class Transformer(TransformSpec):
             self.document.note_transform_message)
         while self.transforms:
             if not self.sorted:
-                # Unsorted initially, and whenever a transform is added.
-                self.transforms.sort()
-                self.transforms.reverse()
-                self.sorted = 1
+                # Unsorted initially, and whenever a transform is added
+                # (transforms may add other transforms).
+                self.transforms.sort(reverse=True)
+                self.sorted = True
             priority, transform_class, pending, kwargs = self.transforms.pop()
             transform = transform_class(self.document, startnode=pending)
             transform.apply(**kwargs)