[TASK] Improve docs on creating images

linawolf · linawolf · commit 8d6e98994a4e · 2025-05-03T09:27:29.000+02:00
diff --git a/Documentation/Advanced/GuidelinesForImages.rst b/Documentation/Advanced/GuidelinesForImages.rst
@@ -9,9 +9,11 @@
 Guidelines for creating images
 ==============================
 
-Read here how to embed an image into ReST: :ref:`Images <h2document:images>`.
+For accessibility reasons **always** provide an alt text:
 
-For accessibility reasons always provide an alt text.
+..  literalinclude:: /_CodeSnippets/_Figure.rts.txt
+
+More option for embedding images into ReST: :ref:`Images <h2document:images>`.
 
 ..  _guidelines-for-images-formats:
 
@@ -22,6 +24,7 @@ Image formats
    and SVG for vector graphics images. In any case, you can use .png.
 
 ..  _guidelines-for-images-screenshot:
+..  _automatic-screenshots:
 
 Guidelines for screenshots
 ==========================
@@ -62,7 +65,6 @@ or locally on DDEV to make screenshots:
 
 `Ready to use Project for screenshots <https://github.com/TYPO3-Documentation/site-introduction/blob/main/Readme.md>`_
 
-
 ..  _guidelines-for-images-screenshot-with-grafics:
 
 Guidelines for screenshots with graphics elements
diff --git a/Documentation/Basics/RstCheatSheet.rst b/Documentation/Basics/RstCheatSheet.rst
@@ -142,12 +142,7 @@ confval menues: :ref:`rest-confval`.
 Figures and Images
 ==================
 
-..  code-block:: rst
-
-    ..  figure:: /_Images/a4.jpg
-        :alt: some image
-
-    The caption of the image
+..  literalinclude:: /_CodeSnippets/_Figure.rts.txt
 
 *   :ref:`Images in reST <h2document:images>`
 *   :ref:`Guidelines for creating images <h2document:guidelines-for-images>`
diff --git a/Documentation/Reference/ReStructuredText/Graphics/Diagrams.rst b/Documentation/Reference/ReStructuredText/Graphics/Diagrams.rst
@@ -11,10 +11,7 @@ PlantUML diagrams
 In order to render diagrams in the TYPO3 documentation,
 `PlantUML <https://plantuml.com/>`_ is integrated into the rendering process.
 
-Embedded UML diagrams
-=====================
-
-Simple diagrams can be embedded directly into the reStructuredText markup:
+Basic diagrams can be embedded directly into the reStructuredText markup:
 
 ..  code-block:: rst
     :caption: Documentation/SomeFile.rst
@@ -31,6 +28,8 @@ This will be rendered as:
 
     class -> otherClass : message
 
+..  _PlantUML-diagrams-included:
+
 Include a PlantUML file
 =======================
 
diff --git a/Documentation/Reference/ReStructuredText/Graphics/Images.rst b/Documentation/Reference/ReStructuredText/Graphics/Images.rst
@@ -1,61 +1,51 @@
+:navigation-title: Images
+
 ..  include:: /Includes.rst.txt
 ..  index:: pair: reST; Images
 ..  _how-to-document-images:
-..  _rest-images:
 ..  _images:
 
-======
-Images
-======
-
-..  index:: automatic screenshot generation
-..  _automatic-screenshots:
-
-Automatic screenshot generation
-===============================
+==================================
+Using images in ReST documentation
+==================================
 
-See the `README in the t3docs-screenshots <https://github.com/TYPO3-Documentation/t3docs-screenshots/blob/main/README.rst>`__
-for more information on automating screenshot generation.
+You can use the `The example screenshot project <https://docs.typo3.org/permalink/h2document:screenshot-project>`_.
+It already follows most of the rules stated below. There has been no automatic
+screenshot tool since TYPO3 v11 as it proved to be to complicated to maintain.
 
-..  index:: reST directives; image
+..  attention::
 
-How to use images
-=================
+    For official and Core manuals please follow the
+    `Guidelines for creating images <https://docs.typo3.org/permalink/h2document:guidelines-for-images>`_.
 
-Use the `..  image::` directive with additional parameters.
-
-Use `..  figure::` if you want to add a caption to your image.
-You can use the same parameters in figure that are defined for image.
-
-The
-additional parameters must be indented one level (add 4 spaces to indent).
+..  _rest-images:
 
-Recommended parameters for images:
+Images and figures in Rest
+==========================
 
-*   `:class: with-shadow`
+We recommend to use the `..  figure::` directive. It works just like
+`..  image::` save that you can add a descriptive text as content.
 
-Alternatively, a border can be defined:
+Always use the parameter `:alt:` to add a descriptive text for visually impaired
+and search engine / artificial intelligence bots scanning our docs.
 
-*   `:class: with-border`
+Example:
 
+..  literalinclude:: /_CodeSnippets/_Figure.rts.txt
 
-Optional parameters for images:
+Optional parameters for images and figures:
 
-*   `:alt:` : alt text
 *   `:target:` link target
 *   `:width:` : width of image, use for example px (for example `:width: 100px`
 *   `:scale:` : scale images, for example `:scale: 65`
 
 Additional parameters can be found on the docutils page `reStructuredText Directives
 <http://docutils.sourceforge.net/0.4/docs/ref/rst/directives.html#image>`__
 
-Examples
-========
-
-..  index:: reST; Image scaling
+..  _image-scaled:
 
 Example 1: Scaled image with shadow and link target
----------------------------------------------------
+===================================================
 
 ..  image:: /_Images/a4.jpg
     :alt: Left floating image
@@ -66,37 +56,20 @@ Example 1: Scaled image with shadow and link target
 ..  code-block:: rst
     :linenos:
 
-    ..  image:: /_Images/a4.jpg
+    ..  figure:: /_Images/a4.jpg
         :alt: some image
         :target: https://typo3.org
         :class: with-shadow
         :scale: 50
 
+..  _image-caption:
 
-**line 1:**
-    image directive with path
-
-**line 2:**
-    alt-Text
-
-**line 3:**
-    link target
-
-**line 4:**
-    use a shadow on the image
-
-
-..  index::
-    reST directives; figure
-    reST; Image caption
-
-Example 2: Image with caption
------------------------------
+Example 2: Image with caption and fixed width
+=============================================
 
 ..  figure:: /_Images/a4.jpg
     :alt: Left floating image
     :target: https://typo3.org
-    :class: with-shadow
     :width: 100px
 
     This is the image caption
@@ -107,75 +80,6 @@ Example 2: Image with caption
         ..  figure:: /_Images/a4.jpg
             :alt: some image
             :target: https://typo3.org
-            :class: with-shadow
             :width: 100px
 
             This is the image caption
-
-**line 5:**
-    width of image
-
-
-Example 3: Image with fixed width
----------------------------------
-
-..  image:: /_Images/a4.jpg
-    :alt: Left floating image
-    :target: https://typo3.org
-    :class: with-shadow
-    :width: 100px
-
-
-..  code-block:: rst
-    :linenos:
-
-    ..  image:: /_Images/a4.jpg
-        :alt: some image
-        :target: https://typo3.org
-        :class: with-shadow
-        :width: 100px
-
-**line 5:**
-    width of image
-
-
-..  index:: reST; Image floating
-
-
-Example 4: Image with float-left
---------------------------------
-
-..  image:: /_Images/a4.jpg
-    :alt: Left floating image
-    :target: https://typo3.org
-    :class: with-shadow float-left
-
-Some text ...  (will be displayed on the right of the image).
-
-..  rst-class::  clear-both
-
-
-..  code-block:: rst
-
-    ..  image:: /_Images/a4.jpg
-        :alt: Left floating image
-        :target: https://typo3.org
-        :class: with-shadow float-left
-
-    Some text ...  (will be displayed on the right of the image)
-
-    ..  rst-class::  clear-both
-
-
-..  hint::
-
-    When using float-left, make sure the text is suitable for
-    wrapping around images. Here, we use `..  rst-class:: clear-both`
-    to reset the floating and start on the left again.
-
-
-Example 5: Image with border
-----------------------------
-
-..  image:: /_Images/a4.jpg
-    :class: with-border
diff --git a/Documentation/Reference/ReStructuredText/Graphics/Index.rst b/Documentation/Reference/ReStructuredText/Graphics/Index.rst
@@ -1,12 +1,26 @@
 ..  include:: /Includes.rst.txt
 ..  _rest-images-diagrams:
 
-===========================
-Graphs, images and diagrams
-===========================
+====================
+Figures and diagrams
+====================
+
+You can upload images in any folder below `Documentation` and use it like that:
+
+..  literalinclude:: /_CodeSnippets/_Figure.rts.txt
+
+For details see `Using images in ReST documentation <https://docs.typo3.org/permalink/h2document:images>`_.
+
+You can also use `Embedded PlantUML diagrams <https://docs.typo3.org/permalink/h2document:plantuml-diagrams>`_.
+
+..  attention::
+
+    For official and Core manuals please follow the
+    `Guidelines for creating images <https://docs.typo3.org/permalink/h2document:guidelines-for-images>`_.
 
 ..  toctree::
     :titlesonly:
     :glob:
 
+    Images
     *
diff --git a/Documentation/_CodeSnippets/_Figure.rts.txt b/Documentation/_CodeSnippets/_Figure.rts.txt
@@ -0,0 +1,4 @@
+..  figure:: /_Images/a4.jpg
+    :alt: some image
+
+    This is the image caption
