docs: document image/figure float and alignment (#510)

* docs: document image/figure float and alignment options

Add documentation for the new CSS float and alignment support for images
and figures introduced in render-guides 0.37.0. Split the monolithic
Images.rst into three focused pages:

- Images.rst: basics, parameters, Examples 1-2
- ImageZoom.rst: zoom modes, options, accessibility, Examples 3-7
- ImageAlignment.rst: float/align, clearing, responsive, Examples 8-10

Depends on: TYPO3-Documentation/render-guides#1174

* fix: correct heading underline characters for TYPO3 convention

When ImageZoom.rst and ImageAlignment.rst were extracted from Images.rst
into their own pages, heading underline characters were not promoted to
match the new document hierarchy. Sections that were h3/h4 in the parent
document need to become h2/h3 as standalone pages.

TYPO3 heading convention:
- h1: = above and below (page title)
- h2: = below only (sections)
- h3: - below only (subsections)
- h4: ~ below only (sub-subsections)

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>

---------

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>

Author: CybotTM

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