SF.net SVN: docutils:[10102 ] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Wed, 23 Apr 2025 15:54:44 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
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.
_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins