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

Revision: 10169
          http://sourceforge.net/p/docutils/code/10169
Author:   milde
Date:     2025-06-16 10:05:35 +0000 (Mon, 16 Jun 2025)
Log Message:
-----------
Add alias "rst-class" for the "class" directive.

Improves the compatibility with Sphinx which overwrites the "class" directive
with "domain specific" directives (by default  "py:class").

The alias is added to the English-language mappings for directive names
(similar to "section-numbering") so that missing translations don't lead
failures. As English names are used as fallback, the alias works independent
of the document language.

Modified Paths:
--------------
    trunk/docutils/HISTORY.rst
    trunk/docutils/RELEASE-NOTES.rst
    trunk/docutils/docs/ref/rst/directives.rst
    trunk/docutils/docutils/parsers/rst/languages/en.py
    trunk/docutils/test/test_parsers/test_rst/test_directives/test_class.py

Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst	2025-06-16 09:58:04 UTC (rev 10168)
+++ trunk/docutils/HISTORY.rst	2025-06-16 10:05:35 UTC (rev 10169)
@@ -24,6 +24,12 @@
   external target but "name" must be unique across the document.
   So far, the name was silently dropped.
 
+* docutils/parsers/rst/languages/en.py
+
+  Add alias "rst-class" for the "class" directive to improve the
+  compatibility with Sphinx.
+
+
 Release 0.22rc3 (2025-06-10)
 ============================
 

Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst	2025-06-16 09:58:04 UTC (rev 10168)
+++ trunk/docutils/RELEASE-NOTES.rst	2025-06-16 10:05:35 UTC (rev 10169)
@@ -250,6 +250,8 @@
 Drop the "name" option of the "target-notes" directive.
 (Report an error instead of silently ignoring the value.)
 
+New alias "rst-class" for the `"class"`_ directive to improve the
+compatibility with Sphinx.
 
 
 Release 0.22rc3 (2025-06-10)
@@ -1484,6 +1486,7 @@
 .. _"colwidth" attribute: docs/ref/doctree.html#colwidth
 .. _<doctest_block>: docs/ref/doctree.html#doctest-block
 
+.. _"class": docs/ref/rst/directives.html#class
 .. _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

Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst	2025-06-16 09:58:04 UTC (rev 10168)
+++ trunk/docutils/docs/ref/rst/directives.rst	2025-06-16 10:05:35 UTC (rev 10169)
@@ -1277,7 +1277,7 @@
 These directives may be used multiple times, cumulatively.  There is
 currently support for only one header and footer.
 
-.. note::
+.. tip::
 
    While it is possible to use the "header" and "footer" directives to
    create navigational elements for web pages, you should be aware
@@ -1289,8 +1289,6 @@
    documentation generator like Sphinx_ rather than the "header" and
    "footer" directives.
 
-   .. _Sphinx: http://sphinx-doc.org/
-
 In addition to the use of these directives to populate header and
 footer content, content may also be added automatically by the
 processing system.  For example, if certain runtime settings are
@@ -1740,6 +1738,7 @@
 
 
 .. _class directive:
+.. _rst-class:
 
 Class
 =====
@@ -1746,7 +1745,7 @@
 
 .. class:: field-indent-13em
 
-:Directive Type: "class"
+:Directive Type: "class" or "rst-class" (synonyms) [#]_
 :Doctree Element: `\<pending>`_
 :Directive Arguments: one or more, required
                       (class names / attribute values)
@@ -1812,6 +1811,14 @@
         <paragraph>
             Special block quote.
 
+.. [#] Sphinx_ uses the directive name "class" for `domain specific`__
+   directives (by default "`py:class`__").
+   The "rst-class" synonym is compatible with Sphinx.
+
+   __ https://www.sphinx-doc.org/en/master/usage/domains/
+   __ https://www.sphinx-doc.org/en/master/usage/domains/python.html
+      #directive-py-class
+
 .. [#] Elements that are not shown in the output (comments_,
    `substitution definitions`_, `hyperlink targets`_, ...) as well as
    "header_" and "footer_" directives are skipped.
@@ -2258,8 +2265,11 @@
   Whitespace is removed (cf. `external hyperlink targets`_ in the
   reStructuredText specification).
 
+.. References
+
 .. _codecs: https://docs.python.org/3/library/codecs.html
 .. _relative reference: https://www.rfc-editor.org/rfc/rfc3986.html#section-4.2
+.. _Sphinx: http://sphinx-doc.org/
 .. _Standard Encodings:
     https://docs.python.org/3/library/codecs.html#standard-encodings
 

Modified: trunk/docutils/docutils/parsers/rst/languages/en.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/languages/en.py	2025-06-16 09:58:04 UTC (rev 10168)
+++ trunk/docutils/docutils/parsers/rst/languages/en.py	2025-06-16 10:05:35 UTC (rev 10169)
@@ -54,6 +54,7 @@
       'unicode': 'unicode',
       'date': 'date',
       'class': 'class',
+      'rst-class': 'class',  # Sphinx compatibility alias
       'role': 'role',
       'default-role': 'default-role',
       'title': 'title',

Modified: trunk/docutils/test/test_parsers/test_rst/test_directives/test_class.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_directives/test_class.py	2025-06-16 09:58:04 UTC (rev 10168)
+++ trunk/docutils/test/test_parsers/test_rst/test_directives/test_class.py	2025-06-16 10:05:35 UTC (rev 10169)
@@ -23,6 +23,9 @@
 
 
 class ParserTestCase(unittest.TestCase):
+
+    maxDiff = None
+
     def test_parser(self):
         parser = Parser()
         settings = get_default_settings(Parser)
@@ -65,6 +68,25 @@
     <paragraph classes="class1 class2">
         And this one.
 """],
+["""\
+.. rst-class:: class1  class2
+..
+
+   The classes will be applied to this block quote.
+""",
+"""\
+<document source="test data">
+    <pending>
+        .. internal attributes:
+             .transform: docutils.transforms.misc.ClassAttribute
+             .details:
+               class: ['class1', 'class2']
+               directive: 'rst-class'
+    <comment xml:space="preserve">
+    <block_quote>
+        <paragraph>
+            The classes will be applied to this block quote.
+"""],
 ]
 
 

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