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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 10102
          http://sourceforge.net/p/docutils/code/10102
Author:   milde
Date:     2025-04-23 15:54:44 +0000 (Wed, 23 Apr 2025)
Log Message:
-----------
New option "figname" for the "figure" directive.

Fixes [feature-requests:#44].

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/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	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/HISTORY.rst	2025-04-23 15:54:44 UTC (rev 10102)
@@ -90,6 +90,11 @@
 
   - Support CSS3 `length units`_. Fixes feature-request #57.
 
+* docutils/parsers/rst/directives/images.py
+
+  - New option "figname" for the "figure" directive.
+    Fixes feature-request #44.
+
 * docutils/parsers/rst/directives/misc.py
 
   - Pass the included file's path to the parser when the

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-04-23 15:54:44 UTC (rev 10102)
@@ -57,7 +57,7 @@
 * The <footnote> element's first child (<label>) will become mandatory
   in Docutils 1.0.
 
-* The "rst" parser will warn if a "figure" directive is missing both
+* The "rst" parser will warn if a `"figure"`_ directive is missing both
   caption and legend in Docutils 1.0.
 
 * To match the definition in the "Exchange Table Model", the
@@ -221,10 +221,12 @@
 ===============================
 
 reStructuredText:
-  Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
-  "vmax", and "Q" to the `supported length units`__.
-  Note that some output formats don't support all units.
+  - Support `CSS3 units`_. This adds "ch", "rem", "vw", "vh", "vmin",
+    "vmax", and "Q" to the `supported length units`__. Note that some
+    output formats don't support all units.
 
+  - New option "figname" for the `"figure"`_ directive.
+
   .. _CSS3 units: https://www.w3.org/TR/css-values-3/#lengths
   __ docs/ref/rst/restructuredtext.html#length-units
 
@@ -1050,14 +1052,14 @@
   - most directives now support a "name" option that attaches a
     reference name. So you can write ::
 
-      .. figure:: image.png
-         :name: figure name
+      .. image:: image.png
+         :name: image name
 
     as a short form of ::
 
-      .. _figure name:
+      .. _image name:
 
-      .. figure:: image.png
+      .. image:: image.png
 
 Internationalization:
 
@@ -1146,9 +1148,7 @@
 * reStructuredText:
 
   - Allow length units for all length specifications.
-  - Allow percent sign in "scale" argument of "figure" and "image" directives.
-  - Bugfix: The "figalign" argument of a figure now works as intended
-    (aligning the figure not its contents).
+  - Allow percent sign in "scale" option of "figure" and "image_" directives.
   - Align images with class "align-[right|center|left]"
     (allows setting the alignment of an image in a figure).
   - Hard tabs **in literal inclusions** are replaced by spaces.
@@ -1184,6 +1184,8 @@
   - Typeset generic topic as "quote with title".
   - Use template (file and configuration option).
   - Render doctest blocks as literal blocks (indented).
+  - Bugfix: The "align" argument of a figure now works as documented
+    (aligning the figure, not its contents).
 
 * ODT writer:
 
@@ -1412,6 +1414,7 @@
 .. _csv-table: docs/ref/rst/directives.html#csv-table
 .. _"date": docs/ref/rst/directives.html#date
 .. _doctest block: docs/ref/rst/restructuredtext.html#doctest-blocks
+.. _"figure": docs/ref/rst/directives.html#figure
 .. _identifier normalization:
     docs/ref/rst/directives.html#identifier-normalization
 .. _image: docs/ref/rst/directives.html#image

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-04-23 15:54:44 UTC (rev 10102)
@@ -33,11 +33,11 @@
 details.
 
 Descriptions below list "doctree elements" (document tree element
-names; XML DTD generic identifiers) corresponding to individual
-directives.  For details on the hierarchy of elements, please see `The
-Docutils Document Tree`_ and the `Docutils Generic DTD`_ XML document
-type definition.  For directive implementation details, see `Creating
-reStructuredText Directives`_.
+names; XML DTD generic identifiers) corresponding to individual directives.
+For details on the hierarchy of elements, please see `The Docutils
+Document Tree`_ and the `Docutils Generic DTD`_ XML document type definition.
+For directive implementation details, see `Creating reStructuredText
+Directives`_ and the `source <../../../docutils/parsers/rst/directives>`__.
 
 .. _Docutils Generic DTD: ../docutils.dtd
 .. _Creating reStructuredText Directives:
@@ -375,17 +375,27 @@
 
 .. _figure options:
 
-The "figure" directive supports all `options of the "image" directive
-<image options_>`__. These options (except ``align``) are passed on
-to the contained image.
+The "figure" directive supports the `common options`_ and all
+`options of the "image" directive <image options_>`__.
+These options (except ``align``) are passed on to the contained image.
 
 ``align`` : "left", "center", or "right"
-    The horizontal alignment of the figure, allowing the image to
-    float and have the text flow around it.  The specific behaviour
-    depends upon the browser or rendering software used.
+    The horizontal alignment of the figure.  The specific behaviour
+    depends upon the browser or rendering software used. In HTML, the
+    values "left" and "right" allow text to flow around the figure.
 
 In addition, the following options are recognized:
 
+``figclass`` : space separated list of `class names`_
+    Set a `classes attribute`_ value on the <figure> element
+    (the "class__" option is applied to the nested <image>).
+
+    __ `class option`_
+
+``figname`` : text_
+    Add *text* to the `names attribute`_ of the <figure> element
+    (the "name_" option is applied to the nested <image>).
+
 ``figwidth`` : "image", length_, or percentage_ of current line width
     The width of the figure.
     Limits the horizontal space used by the figure.
@@ -394,7 +404,7 @@
     Library`_). If the image file is not found or the required software is
     unavailable, this option is ignored.
 
-    Sets the `width attribute`_ of the <figure> doctree element.
+    Sets the `width attribute`_ of the `\<figure>`_ doctree element.
 
     This option does not scale the included image; use the ``width``
     `image option <image options_>`__ for that. ::
@@ -414,10 +424,6 @@
         |wrap at this width.        |
         +---------------------------+
 
-``figclass`` : space separated list of `class names`_
-    Set a `classes attribute`_ value on the figure element.  See the
-    `class directive`_ below.
-
 .. _Python Imaging Library:
 .. _Pillow: https://pypi.org/project/Pillow/
 
@@ -1768,7 +1774,7 @@
 
        Second paragraph.
 
-The text above is parsed and transformed into this doctree fragment::
+The text above is parsed and transformed into this doctree_ fragment::
 
     <paragraph classes="special">
         This is a "special" paragraph.
@@ -2290,7 +2296,8 @@
 
 .. _reStructuredText Standard Definition Files: definitions.html
 
-.. _The Docutils Document Tree: ../doctree.html
+.. _The Docutils Document Tree:
+.. _doctree: ../doctree.html
 .. _identifiers: ../doctree.html#identifiers
 .. _inline elements: ../doctree.html#inline-elements
 .. _class names: ../doctree.html#class-names

Modified: trunk/docutils/docutils/parsers/rst/directives/images.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/directives/images.py	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/docutils/parsers/rst/directives/images.py	2025-04-23 15:54:44 UTC (rev 10102)
@@ -119,8 +119,10 @@
             return directives.length_or_percentage_or_unitless(argument, 'px')
 
     option_spec = Image.option_spec.copy()
+
     option_spec['figwidth'] = figwidth_value
     option_spec['figclass'] = directives.class_option
+    option_spec['figname'] = directives.unchanged
     option_spec['align'] = align
     has_content = True
 
@@ -127,6 +129,7 @@
     def run(self):
         figwidth = self.options.pop('figwidth', None)
         figclasses = self.options.pop('figclass', None)
+        figname = self.options.pop('figname', None)
         align = self.options.pop('align', None)
         (image_node,) = Image.run(self)
         if isinstance(image_node, nodes.system_message):
@@ -149,6 +152,9 @@
             figure_node['width'] = figwidth
         if figclasses:
             figure_node['classes'] += figclasses
+        if figname:
+            figure_node['names'].append(nodes.fully_normalize_name(figname))
+            self.state.document.note_explicit_target(figure_node, figure_node)
         if align:
             figure_node['align'] = align
         if self.content:

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	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_figures.py	2025-04-23 15:54:44 UTC (rev 10102)
@@ -146,8 +146,9 @@
 """],
 ["""\
 .. Figure:: picture.png
+   :alt: alternate text
+   :name: img:picture
    :height: 100
-   :alt: alternate text
    :width: 200
    :scale: 50
    :loading: lazy
@@ -154,14 +155,14 @@
    :class: image-class
    :figwidth: 300
    :figclass: class1 class2
-   :name: fig:pix
+   :figname: Fig:  pix
 
    A figure with options and this caption.
 """,
 """\
 <document source="test data">
-    <figure classes="class1 class2" width="300px">
-        <image alt="alternate text" classes="image-class" height="100" ids="fig-pix" loading="lazy" names="fig:pix" scale="50" uri="picture.png" width="200">
+    <figure classes="class1 class2" ids="fig-pix" names="fig:\\ pix" width="300px">
+        <image alt="alternate text" classes="image-class" height="100" ids="img-picture" loading="lazy" names="img:picture" scale="50" uri="picture.png" width="200">
         <caption>
             A figure with options and this caption.
 """],

Modified: trunk/docutils/test/test_writers/test_html4css1.py
===================================================================
--- trunk/docutils/test/test_writers/test_html4css1.py	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/test/test_writers/test_html4css1.py	2025-04-23 15:54:44 UTC (rev 10102)
@@ -306,6 +306,7 @@
 ],
 ["""\
 .. figure:: dummy.png
+   :figname: fig:dummy
 
    The figure's caption.
 
@@ -314,7 +315,7 @@
    The legend's second paragraph.
 """,
 """\
-<div class="figure">
+<div class="figure" id="fig-dummy">
 <img alt="dummy.png" src="dummy.png" />
 <p class="caption">The figure's caption.</p>
 <div class="legend">

Modified: trunk/docutils/test/test_writers/test_html5_polyglot.py
===================================================================
--- trunk/docutils/test/test_writers/test_html5_polyglot.py	2025-04-22 14:04:43 UTC (rev 10101)
+++ trunk/docutils/test/test_writers/test_html5_polyglot.py	2025-04-23 15:54:44 UTC (rev 10102)
@@ -326,6 +326,7 @@
 ],
 ["""\
 .. figure:: dummy.png
+   :figname: fig:dummy
 
    The figure's caption.
 
@@ -334,7 +335,7 @@
    The legend's second paragraph.
 """,
 """\
-<figure>
+<figure id="fig-dummy">
 <img alt="dummy.png" src="dummy.png" />
 <figcaption>
 <p>The figure's caption.</p>

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



