SF.net SVN: docutils:[10297 ] trunk/docutils/docutils

Revision: 10297
          http://sourceforge.net/p/docutils/code/10297
Author:   milde
Date:     2026-02-06 09:09:04 +0000 (Fri, 06 Feb 2026)
Log Message:
-----------
Update various comments and docstrings.

Modified Paths:
--------------
    trunk/docutils/docutils/nodes.py
    trunk/docutils/docutils/parsers/rst/directives/parts.py
    trunk/docutils/docutils/transforms/parts.py

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2026-02-06 09:08:56 UTC (rev 10296)
+++ trunk/docutils/docutils/nodes.py	2026-02-06 09:09:04 UTC (rev 10297)
@@ -1913,10 +1913,15 @@
         implicit  None  implicit  None  implicit  new      INFO
         ========  ====  ========  ====  ========  ======== =======  ======
 
-        .. [#] Do not clear the name-to-id map or invalidate the old target if
-           both old and new targets refer to identical URIs or reference names.
-           The new target is invalidated regardless.
+        .. [#] When "invalidating" an element, `name` is transferred from
+           the element's "name" attribute to its "dupnames" attribute.
 
+        .. [#ex] If both "old" and "new" refer to identical URIs or
+           reference names, keep the old state and only invalidate "new".
+
+        __ https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
+           #implicit-hyperlink-targets
+
         Provisional. There will be changes to prefer explicit reference names
         as base for an element's ID.
         """

Modified: trunk/docutils/docutils/parsers/rst/directives/parts.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/parts.py	2026-02-06 09:08:56 UTC (rev 10296)
+++ trunk/docutils/docutils/parsers/rst/directives/parts.py	2026-02-06 09:09:04 UTC (rev 10297)
@@ -66,7 +66,6 @@
                 title = nodes.title('', language.labels['contents'])
         topic = nodes.topic(classes=['contents'])
         topic['classes'] += self.options.get('class', [])
-        # the latex2e writer needs source and line for a warning:
         topic.source, topic.line = self.state_machine.get_source_and_line()
         topic.line -= 1
         if 'local' in self.options:

Modified: trunk/docutils/docutils/transforms/parts.py
===================================================================
--- trunk/docutils/docutils/transforms/parts.py	2026-02-06 09:08:56 UTC (rev 10296)
+++ trunk/docutils/docutils/transforms/parts.py	2026-02-06 09:09:04 UTC (rev 10297)
@@ -78,9 +78,9 @@
     The depth may be specified.  Two-way references between the table of
     contents and section titles are generated (requires Writer support).
 
-    This transform requires a startnode, which contains generation
-    options and provides the location for the generated table of contents (the
-    startnode is replaced by the table of contents "topic").
+    This transform requires a startnode, a "pending" element which contains
+    generation options and provides the location for the generated ToC (the
+    startnode is replaced by the table of contents "bullet-list").
     """
 
     default_priority = 720
@@ -91,11 +91,11 @@
         # TODO: handle "generate_oowriter_toc" setting of the "ODT" writer.
         if toc_by_writer:
             return
+
         details = self.startnode.details
         if 'local' in details:
             startnode = self.startnode.parent.parent
-            while not (isinstance(startnode, nodes.section)
-                       or isinstance(startnode, nodes.document)):
+            while not isinstance(startnode, (nodes.section, nodes.document)):
                 # find the ToC root: a direct ancestor of startnode
                 startnode = startnode.parent
         else:

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