[TASK] Float images with :align: instead of float-left/float-right

Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst

@@ -16,56 +16,35 @@ text wraps around them. This is useful for inline illustrations, icons,
 or any image that should be embedded within a text flow rather than
 displayed as a standalone block.
 
-There are two ways to apply floating:
-
-1.  **CSS classes** :rst:`:class: float-left` or :rst:`:class: float-right` — works on
-    both :rst:`..  image::` and :rst:`..  figure::` directives.
-2.  The :rst:`:align:` **option** — :rst:`:align: left`, :rst:`:align: right`, or :rst:`:align: center`
-    — works on :rst:`..  figure::` directives (internally mapped to the same CSS
-    classes).
-
-Both approaches produce the same visual result. Use whichever fits your
-preference.
-
 ..  _image-float-css-classes:
-
-Float with CSS classes
-======================
-
-Add :rst:`float-left` or :rst:`float-right` to the :rst:`:class:` option. You can combine
-these with other classes such as :rst:`with-shadow` or :rst:`with-border`:
-
-..  code-block:: rst
-
-    ..  figure:: /Images/MyImage.png
-        :alt: Description of the image
-        :class: float-left with-shadow
-
-        Caption text here
-
-    Surrounding text will wrap to the right of the image.
-
 ..  _image-float-align-option:
 
 Align option
 ============
 
-The :rst:`:align:` option on :rst:`..  figure::` directives supports :rst:`left`, :rst:`right`,
-and :rst:`center`. Values :rst:`left` and :rst:`right` produce the same floating behavior
-as the CSS classes:
+Use the :rst:`:align:` option to float an image or figure. It works on both
+:rst:`..  image::` and :rst:`..  figure::` directives and supports :rst:`left`,
+:rst:`right`, and :rst:`center`. Other classes such as :rst:`with-shadow` go
+into the :rst:`:class:` option next to it:
 
 ..  code-block:: rst
 
     ..  figure:: /Images/MyImage.png
         :alt: Description of the image
         :align: right
+        :class: with-shadow
 
         Caption text here
 
     Surrounding text will wrap to the left of the image.
 
 Using :rst:`:align: center` centers the figure without any text wrapping.
 
+The CSS classes :rst:`float-start` and :rst:`float-end` in :rst:`:class:` still
+float an image the same way. The Bootstrap 4 class names :rst:`float-left` and
+:rst:`float-right` are deprecated: the renderer rewrites them to
+:rst:`float-start` and :rst:`float-end` and logs a warning.
+
 ..  _image-float-clearing:
 
 Clearing floats
@@ -79,7 +58,7 @@ floats:
 
     ..  figure:: /Images/MyImage.png
         :alt: Description of the image
-        :class: float-left
+        :align: left
 
         Caption
 
@@ -108,7 +87,8 @@ Example 8: figure floated left
 
 ..  figure:: /_Images/a4.jpg
     :alt: Example figure floated left
-    :class: float-left with-shadow
+    :align: left
+    :class: with-shadow
     :width: 150px
 
     A figure floated to the left
@@ -124,7 +104,8 @@ Typesetting requires one or more fonts.
 
     ..  figure:: /_Images/a4.jpg
         :alt: Example figure floated left
-        :class: float-left with-shadow
+        :align: left
+        :class: with-shadow
         :width: 150px
 
         A figure floated to the left
@@ -174,7 +155,8 @@ Example 10: image floated left with shadow
 
 ..  image:: /_Images/a4.jpg
     :alt: Example image floated left
-    :class: float-left with-shadow
+    :align: left
+    :class: with-shadow
     :width: 150px
 
 Typesetting is the composition of text by means of arranging physical types
@@ -188,7 +170,8 @@ Typesetting requires one or more fonts.
 
     ..  image:: /_Images/a4.jpg
         :alt: Example image floated left
-        :class: float-left with-shadow
+        :align: left
+        :class: with-shadow
         :width: 150px
 
     Typesetting is the composition of text by means of arranging
@@ -206,6 +189,6 @@ Best practices for floating
 *   Set an explicit :rst:`:width:` on floated images to control how much space
     text has to wrap around
 *   Floated figures are limited to 50% of the page width to ensure readability
-*   Prefer :rst:`:align:` on figures for cleaner RST syntax; use :rst:`:class:` when you
-    need to combine float with other classes like :rst:`with-shadow`
+*   Prefer :rst:`:align:` for floating; add other classes like :rst:`with-shadow`
+    with :rst:`:class:` next to it
 *   Test on narrow viewports to verify the responsive behavior

Documentation/Reference/ReStructuredText/Graphics/Images.rst

@@ -40,9 +40,9 @@ Optional parameters for images and figures:
 *   `:width:` : width of image, use for example px (for example `:width: 100px`
 *   `:scale:` : scale images, for example `:scale: 65`
 *   `:zoom:` : enable zoom functionality (see :ref:`image zoom <image-zoom>`)
-*   `:class:` : CSS classes, for example `with-shadow`, `with-border`, `float-left`,
-    `float-right` (see :ref:`floating and alignment <image-float-alignment>`)
-*   `:align:` : alignment/float for figures: `left`, `right`, `center`
+*   `:class:` : CSS classes, for example `with-shadow`, `with-border`, `float-start`,
+    `float-end` (see :ref:`floating and alignment <image-float-alignment>`)
+*   `:align:` : alignment/float for images and figures: `left`, `right`, `center`
     (see :ref:`floating and alignment <image-float-alignment>`)
 
 Additional parameters can be found on the docutils page `reStructuredText Directives