[Docutils-checkins] SF.net SVN: docutils:[10370] trunk/docutils

[<mi...@us...>]

Revision: 10370
          http://sourceforge.net/p/docutils/code/10370
Author:   milde
Date:     2026-06-23 14:59:27 +0000 (Tue, 23 Jun 2026)
Log Message:
-----------
Warn if a "figure" directive is missing both caption and legend.

The `<figure>` Document Tree element's content model mandates an `<image>`
followed by either a `<caption>` or `<legend>` or both.

As a "power-user feature", an empty comment instead of the caption
silences the parser warning (the "--validate" option will still report
an invalid `<figure>`).

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docutils/parsers/rst/directives/images.py
    trunk/docutils/test/data/dependencies.rst
    trunk/docutils/test/functional/expected/dangerous.html
    trunk/docutils/test/functional/expected/rst_html5_tuftig.html
    trunk/docutils/test/functional/input/dangerous.rst
    trunk/docutils/test/functional/input/rst_html5_tuftig.rst
    trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
    trunk/docutils/test/test_writers/test_html4css1.py
    trunk/docutils/test/test_writers/test_html5_polyglot.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/HISTORY.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -69,6 +69,7 @@
 
   - Do not add "name" attribute to `<reference>` elements
     nor set the internal attribute `indirect_reference_name`.
+  - Warn if a `"figure"`_ directive is missing both caption and legend.
 
 * docutils/parsers/rst/directives/tables.py
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/RELEASE-NOTES.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -79,9 +79,6 @@
 Parsers
 -------
 
-* The "rst" parser will warn if a `"figure"`_ directive is missing both
-  caption and legend in Docutils 1.0.
-
 * The `legacy_ids`_ configuration setting default will change to False
   in Docutils 2.0
 
@@ -241,6 +238,9 @@
   - Drop the ``<destination>`` positional argument.
     Use ``-o <destination>`` or output redirection.
 
+rST parser:
+  - Warn if a `"figure"`_ directive is missing both caption and legend.
+
 HTML5 writer:
   - Use normal font size and colour for informal titles of type "rubric".
   - Use more specific CSS selectors for styling <aside> elements as

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/docs/ref/rst/directives.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -376,7 +376,7 @@
        +-----------------------+-----------------------+
 
 There must be blank lines before the caption paragraph and before the
-legend.  To specify a legend without a caption, use an empty comment
+legend.  To specify an image without a caption, use an empty comment
 ("..") in place of the caption.
 
 .. _figure options:

Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py	2026-06-23 14:59:27 UTC (rev 10370)
@@ -155,7 +155,11 @@
             self.state.document.note_explicit_target(figure_node, figure_node)
         if align:
             figure_node['align'] = align
-        if self.content:
+        if not self.content:
+            msg = self.reporter.warning('Figure without caption and legend. '
+                                        'Use "image"?', line=self.lineno)
+            return [figure_node, msg]
+        else:
             # optional caption (single paragraph or empty comment)
             # + optional legend (arbitrary body elements).
             node = nodes.Element()          # anonymous container for parsing

Modified: trunk/docutils/test/data/dependencies.rst
===================================================================
--- trunk/docutils/test/data/dependencies.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/data/dependencies.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -23,6 +23,10 @@
 .. figure:: ../docs/user/rst/images/title.png
    :figwidth: image
 
+   ..
+
+   Image width is read to determine figure width
+
 Scaled images without given size are recorded by the html writer:
 
 .. image:: ../docs/user/rst/images/biohazard.png

Modified: trunk/docutils/test/functional/expected/dangerous.html
===================================================================
--- trunk/docutils/test/functional/expected/dangerous.html	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/expected/dangerous.html	2026-06-23 14:59:27 UTC (rev 10370)
@@ -62,6 +62,7 @@
 </div>
 <div class="figure">
 <img alt="picture.png" src="picture.png" />
+<p class="caption">This image is read by PIL to determine its width.</p>
 </div>
 </div>
 </body>

Modified: trunk/docutils/test/functional/expected/rst_html5_tuftig.html
===================================================================
--- trunk/docutils/test/functional/expected/rst_html5_tuftig.html	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/expected/rst_html5_tuftig.html	2026-06-23 14:59:27 UTC (rev 10370)
@@ -72,10 +72,8 @@
 </div>
 </figcaption>
 </figure>
-<p>To place an image in the margin, use a marginal figure without caption.</p>
-<figure class="marginal">
-<img alt="../../../docs/user/rst/images/biohazard.png" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
-</figure>
+<p>An image with option <span class="docutils literal">:class: marginal</span> moves to the margin as well.</p>
+<img alt="../../../docs/user/rst/images/biohazard.png" class="marginal" src="../../../docs/user/rst/images/biohazard.png" style="width: 2em;" />
 <p>Marginal objects are placed to the right of the preceding main text
 block.</p>
 <aside class="admonition marginal note">

Modified: trunk/docutils/test/functional/input/dangerous.rst
===================================================================
--- trunk/docutils/test/functional/input/dangerous.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/input/dangerous.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -14,3 +14,5 @@
 .. csv-table:: :url: file:///etc/passwd
 .. figure:: picture.png
    :figwidth: image
+
+   This image is read by PIL to determine its width.

Modified: trunk/docutils/test/functional/input/rst_html5_tuftig.rst
===================================================================
--- trunk/docutils/test/functional/input/rst_html5_tuftig.rst	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/functional/input/rst_html5_tuftig.rst	2026-06-23 14:59:27 UTC (rev 10370)
@@ -58,10 +58,10 @@
 
    This is the legend.
 
-To place an image in the margin, use a marginal figure without caption.
+An image with option ``:class: marginal`` moves to the margin as well.
 
-.. figure:: ../../../docs/user/rst/images/biohazard.png
-   :figclass: marginal
+.. image:: ../../../docs/user/rst/images/biohazard.png
+   :class: marginal
    :width: 2em
 
 Marginal objects are placed to the right of the preceding main text

Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py	2026-06-23 14:59:27 UTC (rev 10370)
@@ -49,6 +49,9 @@
 <document source="test data">
     <figure>
         <image uri="picture.png">
+    <system_message level="2" line="1" source="test data" type="WARNING">
+        <paragraph>
+            Figure without caption and legend. Use "image"?
 """],
 ["""\
 .. figure:: picture.png
@@ -277,21 +280,30 @@
 .. figure:: picture.png
 
    A picture with a caption.
+
 .. figure:: picture.png
 
    A picture with a caption.
+
 .. figure:: picture.png
 
    A picture with a caption.
+
 .. figure:: picture.png
 .. figure:: picture.png
+
+   ..
 .. figure:: picture.png
+
+   ..
 .. figure:: picture.png
 
-   A picture with a caption.
+   ..
 
 .. figure:: picture.png
 
+   ..
+
 .. figure:: picture.png
 
    A picture with a caption.
@@ -316,6 +328,9 @@
             A picture with a caption.
     <figure>
         <image uri="picture.png">
+    <system_message level="2" line="15" source="test data" type="WARNING">
+        <paragraph>
+            Figure without caption and legend. Use "image"?
     <figure>
         <image uri="picture.png">
     <figure>
@@ -322,8 +337,6 @@
         <image uri="picture.png">
     <figure>
         <image uri="picture.png">
-        <caption>
-            A picture with a caption.
     <figure>
         <image uri="picture.png">
     <figure>
@@ -332,6 +345,9 @@
             A picture with a caption.
     <figure>
         <image uri="picture.png">
+    <system_message level="2" line="34" source="test data" type="WARNING">
+        <paragraph>
+            Figure without caption and legend. Use "image"?
 """],
 ]
 

Modified: trunk/docutils/test/test_writers/test_html4css1.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1.py	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_writers/test_html4css1.py	2026-06-23 14:59:27 UTC (rev 10370)
@@ -63,6 +63,7 @@
                             'strict_visitor': True,
                             'stylesheet_path': '',
                             'section_self_link': True,
+                            'warning_stream': '',  # suppress warnings
                             **settings_overrides,
                         }
                     )
@@ -361,6 +362,9 @@
 <div class="figure">
 <img alt="dummy.png" src="dummy.png" />
 </div>
+<div class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">&lt;string&gt;</tt>, line 1)</p>
+Figure without caption and legend. Use &quot;image&quot;?</div>
 <p>No caption nor legend.</p>
 """,
 ],
@@ -424,11 +428,14 @@
 .. image:: /data/blue%20square.png
    :scale: 100%
 .. figure:: /data/blue%20square.png
+
+   Embedded image of a blue square.
 """,
 f"""\
 <img alt="/data/blue%20square.png" src="/data/blue%20square.png" {SCALING_OUTPUT}/>
 <div class="figure">
 <img alt="/data/blue%20square.png" src="/data/blue%20square.png" />
+<p class="caption">Embedded image of a blue square.</p>
 </div>
 """
 ],

Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py	2026-06-23 14:59:13 UTC (rev 10369)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py	2026-06-23 14:59:27 UTC (rev 10370)
@@ -85,6 +85,7 @@
                             'strict_visitor': True,
                             'stylesheet_path': '',
                             'section_self_link': True,
+                            'warning_stream': '',  # suppress warnings
                             **settings_overrides,
                         }
                     )
@@ -388,6 +389,10 @@
 <figure>
 <img alt="dummy.png" src="dummy.png" />
 </figure>
+<aside class="system-message">
+<p class="system-message-title">System Message: WARNING/2 (<span class="docutils literal">&lt;string&gt;</span>, line 1)</p>
+<p>Figure without caption and legend. Use &quot;image&quot;?</p>
+</aside>
 <p>No caption nor legend.</p>
 """,
 ],
@@ -426,8 +431,12 @@
 .. image:: dummy.png
    :loading: link
 .. figure:: dummy.png
+
+   Figure with lazy-loading image.
 .. figure:: dummy.png
    :loading: embed
+
+   Image not embedded, because it is unavailable.
 """,
 """\
 <p>Lazy loading by default, overridden by :loading: option
@@ -436,9 +445,15 @@
 <img alt="dummy.png" src="dummy.png" />
 <figure>
 <img alt="dummy.png" loading="lazy" src="dummy.png" />
+<figcaption>
+<p>Figure with lazy-loading image.</p>
+</figcaption>
 </figure>
 <figure>
 <img alt="dummy.png" src="dummy.png" />
+<figcaption>
+<p>Image not embedded, because it is unavailable.</p>
+</figcaption>
 </figure>
 """,
 ],
@@ -453,6 +468,8 @@
 .. image:: /data/blue%20square.png
    :scale: 100%
 .. figure:: /data/blue%20square.png
+
+   Figure with embedded blue square image.
 """,
 f'<img alt="/data/blue%20square.png" {HEIGHT_ATTR}src="data:image/png;base64,'
 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAALElEQVR4nO3NMQ'
@@ -464,6 +481,9 @@
 'iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAALElEQVR4nO3NMQ'
 'EAMAjAsDFjvIhHFCbgSwU0kdXvsn96BwAAAAAAAAAAAIsNnEwBk52VRuMAAAAA'
 'SUVORK5CYII=" />\n'
+'<figcaption>\n'
+'<p>Figure with embedded blue square image.</p>\n'
+'</figcaption>\n'
 '</figure>\n',
 ],
 ])

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