Fix sphinx-doc#4550: The align attribute of figure nodes becomes None…

… by default

To keep compatibility with the standard doctree model of docutils,
this stops to use 'default' value as a default value of the align
attribute for figure and table nodes.

CHANGES

@@ -25,13 +25,16 @@ Incompatible changes
   documents
 * #5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create
   cross-references
+* #4550: The ``align`` attribute of ``figure`` and ``table`` nodes becomes
+  ``None`` by default instead of ``'default'``
 
 Deprecated
 ----------
 
 * ``sphinx.directives.patches.CSVTable``
 * ``sphinx.directives.patches.ListTable``
 * ``sphinx.directives.patches.RSTTable``
+* ``sphinx.transforms.FigureAligner``
 * ``sphinx.util.pycompat.convert_with_2to3()``
 * ``sphinx.util.pycompat.execfile_()``
 * ``sphinx.util.smartypants``

doc/extdev/deprecated.rst

@@ -41,6 +41,11 @@ The following is a list of deprecated interfaces.
      - 6.0
      - ``docutils.parsers.rst.diretives.tables.RSTTable``
 
+   * - ``sphinx.transforms.FigureAligner``
+     - 4.0
+     - 6.0
+     - N/A
+
    * - ``sphinx.util.pycompat.convert_with_2to3()``
      - 4.0
      - 6.0

sphinx/transforms/__init__.py

@@ -9,6 +9,7 @@
 """
 
 import re
+import warnings
 from typing import TYPE_CHECKING, Any, Dict, Generator, List, Tuple
 
 from docutils import nodes
@@ -21,6 +22,7 @@
 
 from sphinx import addnodes
 from sphinx.config import Config
+from sphinx.deprecation import RemovedInSphinx60Warning
 from sphinx.locale import _, __
 from sphinx.util import docutils, logging
 from sphinx.util.docutils import new_document
@@ -284,6 +286,11 @@ class FigureAligner(SphinxTransform):
     """
     default_priority = 700
 
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn('FigureAilgner is deprecated.',
+                      RemovedInSphinx60Warning)
+        super().__init__(*args, **kwargs)
+
     def apply(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(nodes.table, nodes.figure)
         for node in self.document.traverse(matcher):  # type: Element
@@ -406,7 +413,6 @@ def setup(app: "Sphinx") -> Dict[str, Any]:
     app.add_transform(HandleCodeBlocks)
     app.add_transform(SortIds)
     app.add_transform(DoctestTransform)
-    app.add_transform(FigureAligner)
     app.add_transform(AutoNumbering)
     app.add_transform(AutoIndexUpgrader)
     app.add_transform(FilterSystemMessages)

sphinx/writers/html.py

@@ -573,6 +573,13 @@ def visit_download_reference(self, node: Element) -> None:
     def depart_download_reference(self, node: Element) -> None:
         self.body.append(self.context.pop())
 
+    # overwritten
+    def visit_figure(self, node: Element) -> None:
+        # set align=default if align not specified to give a default style
+        node.setdefault('align', 'default')
+
+        return super().visit_figure(node)
+
     # overwritten
     def visit_image(self, node: Element) -> None:
         olduri = node['uri']
@@ -774,6 +781,10 @@ def depart_manpage(self, node: Element) -> None:
 
     def visit_table(self, node: Element) -> None:
         self._table_row_index = 0
+
+        # set align=default if align not specified to give a default style
+        node.setdefault('align', 'default')
+
         return super().visit_table(node)
 
     def visit_row(self, node: Element) -> None:

sphinx/writers/html5.py

@@ -515,6 +515,13 @@ def visit_download_reference(self, node: Element) -> None:
     def depart_download_reference(self, node: Element) -> None:
         self.body.append(self.context.pop())
 
+    # overwritten
+    def visit_figure(self, node: Element) -> None:
+        # set align=default if align not specified to give a default style
+        node.setdefault('align', 'default')
+
+        return super().visit_figure(node)
+
     # overwritten
     def visit_image(self, node: Element) -> None:
         olduri = node['uri']
@@ -716,8 +723,10 @@ def visit_table(self, node: Element) -> None:
         atts = {}
         classes = [cls.strip(' \t\n') for cls in self.settings.table_style.split(',')]
         classes.insert(0, "docutils")  # compat
-        if 'align' in node:
-            classes.append('align-%s' % node['align'])
+
+        # set align-default if align not specified to give a default style
+        classes.append('align-%s' % node.get('align', 'default'))
+
         if 'width' in node:
             atts['style'] = 'width: %s' % node['width']
         tag = self.starttag(node, 'table', CLASS=' '.join(classes), **atts)

sphinx/writers/latex.py

@@ -106,7 +106,7 @@ class Table:
     def __init__(self, node: Element) -> None:
         self.header = []                        # type: List[str]
         self.body = []                          # type: List[str]
-        self.align = node.get('align')
+        self.align = node.get('align', 'default')
         self.colcount = 0
         self.colspec = None                     # type: str
         self.colwidths = []                     # type: List[int]
@@ -1233,25 +1233,27 @@ def visit_image(self, node: Element) -> None:
                 # to the available text width if oversized after rescaling.
                 include_graphics_options.append('scale=%s'
                                                 % (float(attrs['scale']) / 100.0))
-        if 'align' in attrs:
-            align_prepost = {
-                # By default latex aligns the top of an image.
-                (1, 'top'): ('', ''),
-                (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'),
-                (1, 'bottom'): ('\\raisebox{-\\height}{', '}'),
-                (0, 'center'): ('{\\hspace*{\\fill}', '\\hspace*{\\fill}}'),
-                (0, 'default'): ('{\\hspace*{\\fill}', '\\hspace*{\\fill}}'),
-                # These 2 don't exactly do the right thing.  The image should
-                # be floated alongside the paragraph.  See
-                # https://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG
-                (0, 'left'): ('{', '\\hspace*{\\fill}}'),
-                (0, 'right'): ('{\\hspace*{\\fill}', '}'),
-            }
-            try:
-                pre.append(align_prepost[is_inline, attrs['align']][0])
-                post.append(align_prepost[is_inline, attrs['align']][1])
-            except KeyError:
-                pass
+        # image alignment
+        align = attrs.get('align', 'default')
+        align_prepost = {
+            # By default latex aligns the top of an image.
+            (1, 'top'): ('', ''),
+            (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'),
+            (1, 'bottom'): ('\\raisebox{-\\height}{', '}'),
+            (0, 'center'): ('{\\hspace*{\\fill}', '\\hspace*{\\fill}}'),
+            (0, 'default'): ('{\\hspace*{\\fill}', '\\hspace*{\\fill}}'),
+            # These 2 don't exactly do the right thing.  The image should
+            # be floated alongside the paragraph.  See
+            # https://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG
+            (0, 'left'): ('{', '\\hspace*{\\fill}}'),
+            (0, 'right'): ('{\\hspace*{\\fill}', '}'),
+        }
+        try:
+            pre.append(align_prepost[is_inline, align][0])
+            post.append(align_prepost[is_inline, align][1])
+        except KeyError:
+            pass
+
         if self.in_parsed_literal:
             pre.append('{\\sphinxunactivateextrasandspace ')
             post.append('}')