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

Revision: 10376
          http://sourceforge.net/p/docutils/code/10376
Author:   milde
Date:     2026-06-29 14:03:43 +0000 (Mon, 29 Jun 2026)
Log Message:
-----------
Improve warning for figures without caption.

Move details to a separate paragraph (not shown in console output).

Add hint to cheat with an empty comment in place of the caption.

Note: When cheating with an empty comment, the `<figure>` element
remains invalid (but most writers can handle this).

Fixup for [r10370].

Modified Paths:
--------------
    trunk/docutils/docutils/parsers/rst/directives/images.py
    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/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py	2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py	2026-06-29 14:03:43 UTC (rev 10376)
@@ -156,8 +156,10 @@
         if align:
             figure_node['align'] = align
         if not self.content:
-            msg = self.reporter.warning('Figure without caption and legend. '
-                                        'Use "image"?', line=self.lineno)
+            msg = self.reporter.warning('Figure without caption and legend.',
+                                        line=self.lineno)
+            msg.append(nodes.paragraph('', 'Try the "image" directive '
+                                       '(or cheat with an empty comment).'))
             return [figure_node, msg]
         else:
             # optional caption (single paragraph or empty comment)

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-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py	2026-06-29 14:03:43 UTC (rev 10376)
@@ -51,7 +51,9 @@
         <image uri="picture.png">
     <system_message level="2" line="1" source="test data" type="WARNING">
         <paragraph>
-            Figure without caption and legend. Use "image"?
+            Figure without caption and legend.
+        <paragraph>
+            Try the "image" directive (or cheat with an empty comment).
 """],
 ["""\
 .. figure:: picture.png
@@ -330,7 +332,9 @@
         <image uri="picture.png">
     <system_message level="2" line="15" source="test data" type="WARNING">
         <paragraph>
-            Figure without caption and legend. Use "image"?
+            Figure without caption and legend.
+        <paragraph>
+            Try the "image" directive (or cheat with an empty comment).
     <figure>
         <image uri="picture.png">
     <figure>
@@ -347,7 +351,9 @@
         <image uri="picture.png">
     <system_message level="2" line="34" source="test data" type="WARNING">
         <paragraph>
-            Figure without caption and legend. Use "image"?
+            Figure without caption and legend.
+        <paragraph>
+            Try the "image" directive (or cheat with an empty comment).
 """],
 ]
 

Modified: trunk/docutils/test/test_writers/test_html4css1.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1.py	2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_writers/test_html4css1.py	2026-06-29 14:03:43 UTC (rev 10376)
@@ -364,7 +364,9 @@
 </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>Figure without caption and legend.</p>
+<p>Try the &quot;image&quot; directive (or cheat with an empty comment).</p>
+</div>
 <p>No caption nor legend.</p>
 """,
 ],

Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py	2026-06-27 17:26:02 UTC (rev 10375)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py	2026-06-29 14:03:43 UTC (rev 10376)
@@ -391,7 +391,8 @@
 </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>
+<p>Figure without caption and legend.</p>
+<p>Try the &quot;image&quot; directive (or cheat with an empty comment).</p>
 </aside>
 <p>No caption nor legend.</p>
 """,

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