docs: document image/figure float and alignment

Documentation/Reference/ReStructuredText/Graphics/ImageAlignment.rst

@@ -0,0 +1,211 @@
+:navigation-title: Float and alignment
+
+..  include:: /Includes.rst.txt
+..  _image-float-alignment:
+
+==========================================
+Image and figure floating and alignment
+==========================================
+
+..  versionadded:: 0.37.0
+    Float and alignment support for images and figures was introduced in
+    render-guides version 0.37.0.
+
+Images and figures can be floated to the left or right so that surrounding
+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** ``:class: float-left`` or ``:class: float-right`` — works on
+    both ``..  image::`` and ``..  figure::`` directives.
+2.  The ``:align:`` **option** — ``:align: left``, ``:align: right``, or ``:align: center``
+    — works on ``..  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 ``float-left`` or ``float-right`` to the ``:class:`` option. You can combine
+these with other classes such as ``with-shadow`` or ``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 ``:align:`` option on ``..  figure::`` directives supports ``left``, ``right``,
+and ``center``. Values ``left`` and ``right`` produce the same floating behavior
+as the CSS classes:
+
+..  code-block:: rst
+
+    ..  figure:: /Images/MyImage.png
+        :alt: Description of the image
+        :align: right
+
+        Caption text here
+
+    Surrounding text will wrap to the left of the image.
+
+Using ``:align: center`` centers the figure without any text wrapping.
+
+.. _image-float-clearing:
+
+Clearing floats
+===============
+
+After a floated image, you may want subsequent content to appear below the
+image rather than wrapping around it. Use the ``clear-both`` class to clear
+floats:
+
+..  code-block:: rst
+
+    ..  figure:: /Images/MyImage.png
+        :alt: Description of the image
+        :class: float-left
+
+        Caption
+
+    This text wraps around the image.
+
+    ..  rst-class:: clear-both
+
+    This text appears below the image.
+
+The ``..  rst-class:: clear-both`` directive applies the CSS ``clear: both``
+property to the next element, forcing it below any floated content.
+
+.. _image-float-responsive:
+
+Responsive behavior
+===================
+
+Floated images automatically switch to full-width block display on small
+screens (below 576px). This ensures readable text on mobile devices
+without horizontal scrolling.
+
+.. _image-float-example-8:
+
+Example 8: Figure floated left
+------------------------------
+
+..  figure:: /_Images/a4.jpg
+    :alt: Example figure floated left
+    :class: float-left with-shadow
+    :width: 150px
+
+    A figure floated to the left
+
+Typesetting is the composition of text by means of arranging physical types
+or the digital equivalents. Stored letters and other symbols are retrieved
+and ordered according to a language's orthography for visual display.
+Typesetting requires one or more fonts.
+
+..  rst-class:: clear-both
+
+..  code-block:: rst
+
+    ..  figure:: /_Images/a4.jpg
+        :alt: Example figure floated left
+        :class: float-left with-shadow
+        :width: 150px
+
+        A figure floated to the left
+
+    Typesetting is the composition of text by means of arranging
+    physical types or the digital equivalents. ...
+
+    ..  rst-class:: clear-both
+
+.. _image-float-example-9:
+
+Example 9: Figure aligned right
+--------------------------------
+
+..  figure:: /_Images/a4.jpg
+    :alt: Example figure aligned right
+    :align: right
+    :width: 150px
+
+    A figure aligned right via ``:align:``
+
+Typesetting is the composition of text by means of arranging physical types
+or the digital equivalents. Stored letters and other symbols are retrieved
+and ordered according to a language's orthography for visual display.
+Typesetting requires one or more fonts.
+
+..  rst-class:: clear-both
+
+..  code-block:: rst
+
+    ..  figure:: /_Images/a4.jpg
+        :alt: Example figure aligned right
+        :align: right
+        :width: 150px
+
+        A figure aligned right via :align:
+
+    Typesetting is the composition of text by means of arranging
+    physical types or the digital equivalents. ...
+
+    ..  rst-class:: clear-both
+
+.. _image-float-example-10:
+
+Example 10: Image floated left with shadow
+-------------------------------------------
+
+..  image:: /_Images/a4.jpg
+    :alt: Example image floated left
+    :class: float-left with-shadow
+    :width: 150px
+
+Typesetting is the composition of text by means of arranging physical types
+or the digital equivalents. Stored letters and other symbols are retrieved
+and ordered according to a language's orthography for visual display.
+Typesetting requires one or more fonts.
+
+..  rst-class:: clear-both
+
+..  code-block:: rst
+
+    ..  image:: /_Images/a4.jpg
+        :alt: Example image floated left
+        :class: float-left with-shadow
+        :width: 150px
+
+    Typesetting is the composition of text by means of arranging
+    physical types or the digital equivalents. ...
+
+    ..  rst-class:: clear-both
+
+.. _image-float-best-practices:
+
+Best practices for floating
+============================
+
+*   Always use ``..  rst-class:: clear-both`` after floated content to prevent
+    layout issues with subsequent sections
+*   Set an explicit ``: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 ``:align:`` on figures for cleaner RST syntax; use ``:class:`` when you
+    need to combine float with other classes like ``with-shadow``
+*   Test on narrow viewports to verify the responsive behavior