doc: use 'doc' directory for examples gallery

The initial patch that generates a gallery based on the examples in the
respository, was limited to only showing the content of the files
in each '.pyproject' file.

That approach didn't allow to describe each example, nor add
complementary images, like screenshots to each example page.

This patch introduces the option to consider everything inside a 'doc/'
directory on the example directory. The files that are copied over are
not directory, but only files, for images to be the main focus.

For example, currently the Tetrix case contained the following files:

    $ ls examples/widgets/tetrix/
    tetrix.py
    tetrix.pyproject

On this patch you can see that now there is a doc directory with the
following content:

    $ ls examples/widgets/tetrix/doc
    tetrix-screenshot.png
    tetrix.rst

The example page that will be generated for this case will contain the
content of the 'doc/tetrix.rst' file, plus the content of all the
project files at the end.

The 'doc/tetrix.rst' file contains a reference to the
'tetrix-screenshot.png' image, so that file will be copied over too.

Task-number: PYSIDE-1112
Change-Id: I2d11833c461d8073d2d2888576d876d3f834103a
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
(cherry picked from commit f930fce091fbcc0cdc4d1d57ee688966b26ea53e)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

4 files changed, 118 insertions, 32 deletions

diff --git a/examples/quickcontrols2/gallery/doc/gallery.rst b/examples/quickcontrols2/gallery/doc/gallery.rst
new file mode 100644
index 000000000..29cd49f14
--- /dev/null
+++ b/examples/quickcontrols2/gallery/doc/gallery.rst
@@ -0,0 +1,7 @@
+Qt Quick Controls 2 - Gallery
+=============================
+
+The gallery example is a simple application with a drawer menu that contains
+all the Qt Quick Controls 2. Each menu item opens a page that shows the
+graphical appearance of a control, allows you to interact with the control, and
+explains in which circumstances it is handy to use this control.
diff --git a/examples/widgets/tetrix/doc/tetrix-screenshot.png b/examples/widgets/tetrix/doc/tetrix-screenshot.png
new file mode 100644
index 000000000..2c3dade39
--- /dev/null
+++ b/examples/widgets/tetrix/doc/tetrix-screenshot.png
diff --git a/examples/widgets/tetrix/doc/tetrix.rst b/examples/widgets/tetrix/doc/tetrix.rst
new file mode 100644
index 000000000..0749de9de
--- /dev/null
+++ b/examples/widgets/tetrix/doc/tetrix.rst
@@ -0,0 +1,38 @@
+Tetrix
+======
+
+The Tetrix example is a Qt version of the classic Tetrix game.
+
+.. image:: tetrix-screenshot.png
+  :width: 400
+  :alt: Tetrix main window
+
+The object of the game is to stack pieces dropped from the top of the playing
+area so that they fill entire rows at the bottom of the playing area.
+
+When a row is filled, all the blocks on that row are removed, the player earns
+a number of points, and the pieces above are moved down to occupy that row. If
+more than one row is filled, the blocks on each row are removed, and the player
+earns extra points.
+
+The **Left** cursor key moves the current piece one space to the left, the
+**Right** cursor key moves it one space to the right, the **Up** cursor key
+rotates the piece counter-clockwise by 90 degrees, and the **Down** cursor key
+rotates the piece clockwise by 90 degrees.
+
+To avoid waiting for a piece to fall to the bottom of the board, press **D** to
+immediately move the piece down by one row, or press the **Space** key to drop
+it as close to the bottom of the board as possible.
+
+This example shows how a simple game can be created using only three classes:
+
+* The ``TetrixWindow`` class is used to display the player's score, number of
+  lives, and information about the next piece to appear.
+* The ``TetrixBoard`` class contains the game logic, handles keyboard input, and
+  displays the pieces on the playing area.
+* The ``TetrixPiece`` class contains information about each piece.
+
+In this approach, the ``TetrixBoard`` class is the most complex class, since it
+handles the game logic and rendering. One benefit of this is that the
+``TetrixWindow`` and ``TetrixPiece`` classes are very simple and contain only a
+minimum of code.
diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py
index 4a20760b7..f1a9c4c5f 100644
--- a/tools/example_gallery/main.py
+++ b/tools/example_gallery/main.py
@@ -51,6 +51,7 @@ since there is no special requirements.
 from argparse import ArgumentParser, RawTextHelpFormatter
 import json
 import math
+import shutil
 from pathlib import Path
 from textwrap import dedent
 
@@ -148,6 +149,44 @@ def remove_licenses(s):
     return "\n".join(new_s)
 
 
+def get_code_tabs(files, project_file):
+    content = "\n"
+
+    for i, project_file in enumerate(files):
+        pfile = Path(project_file)
+        if pfile.suffix in (".png", ".pyc"):
+            continue
+
+        if i == 0:
+            content += ".. tabs::\n\n"
+
+        suffix = get_lexer(pfile.suffix)
+        content += add_indent(f".. code-tab:: {suffix} {project_file}", 1)
+        content += "\n"
+
+        _path = f_path.resolve().parents[0] / project_file
+        _file_content = ""
+        with open(_path, "r") as _f:
+            _file_content = remove_licenses(_f.read())
+
+        content += add_indent(_file_content, 2)
+        content += "\n\n"
+    return content
+
+
+def get_header_title(f_path):
+    _title = f_path.stem
+    url_name = "/".join(f_path.parts[f_path.parts.index("examples")+1:-1])
+    url = f"{BASE_URL}/{url_name}"
+    return (
+        "..\n    This file was auto-generated by the 'examples_gallery' "
+        "script.\n    Any change will be lost!\n\n"
+        f"{_title}\n"
+        f"{'=' * len(_title)}\n\n"
+        f"(You can also check this code `in the repository <{url}>`_)\n\n"
+    )
+
+
 if __name__ == "__main__":
     # Only examples with a '.pyproject' file will be listed.
     DIR = Path(__file__).parent
@@ -172,7 +211,7 @@ if __name__ == "__main__":
         if str(f_path).endswith("examples.pyproject"):
             continue
 
-        parts = f_path.parts[len(EXAMPLES_DIR.parts) : -1]
+        parts = f_path.parts[len(EXAMPLES_DIR.parts):-1]
 
         module_name = parts[0]
         example_name = parts[-1]
@@ -181,6 +220,12 @@ if __name__ == "__main__":
 
         rst_file = f"example_{module_name}_{extra_names}_{example_name}.rst"
 
+        # Check for a 'doc' directory inside the example
+        has_doc = False
+        original_doc_dir = Path(f_path.parent / "doc")
+        if original_doc_dir.is_dir():
+            has_doc = True
+
         if module_name not in examples:
             examples[module_name] = []
 
@@ -191,6 +236,7 @@ if __name__ == "__main__":
                 "extra": extra_names,
                 "rst": rst_file,
                 "abs_path": str(f_path),
+                "has_doc": has_doc,
             }
         )
 
@@ -199,38 +245,33 @@ if __name__ == "__main__":
             pyproject = json.load(pyf)
 
         if pyproject:
-            with open(f"{EXAMPLES_DOC}/{rst_file}", "w") as out_f:
-                _title = f_path.stem
-                _title_line = "=" * len(_title)
-                url_name = "/".join(f_path.parts[f_path.parts.index("examples") + 1 : -1])
-                url = f"{BASE_URL}/{url_name}"
-                content_f = (
-                    "..\n    This file was auto-generated by the 'examples_gallery' "
-                    "script.\n    Any change will be lost!\n\n"
-                    f"{_title}\n"
-                    f"{_title_line}\n\n"
-                    f"(You can also check this code `in the repository <{url}>`_)\n\n"
-                )
-                for i, project_file in enumerate(pyproject["files"]):
-                    pfile = Path(project_file)
-                    if pfile.suffix in (".png", ".pyc"):
-                        continue
-
-                    if i == 0:
-                        content_f += ".. tabs::\n\n"
-
-                    lexer = get_lexer(pfile.suffix)
-                    content_f += add_indent(f".. code-tab:: {lexer} {project_file}", 1)
-                    content_f += "\n"
-
-                    _path = f_path.resolve().parents[0] / project_file
-                    _content = ""
-                    with open(_path, "r") as _f:
-                        _content = remove_licenses(_f.read())
-
-                    content_f += add_indent(_content, 2)
-                    content_f += "\n\n"
+            rst_file_full = Path(EXAMPLES_DOC) / rst_file
+
+            with open(rst_file_full, "w") as out_f:
+                if has_doc:
+                    doc_path = Path(f_path.parent) / "doc"
+                    doc_rst = doc_path / f"{example_name}.rst"
+
+                    with open(doc_rst) as doc_f:
+                        content_f = doc_f.read()
+
+                    # Copy other files in the 'doc' directory, but
+                    # excluding the main '.rst' file and all the
+                    # directories.
+                    for _f in doc_path.glob("*"):
+                        if _f == doc_rst or _f.is_dir():
+                            continue
+                        src = _f
+                        dst = Path(EXAMPLES_DOC) / _f.name
+
+                        resource_written = shutil.copy(src, dst)
+                        if not opt_quiet:
+                            print("Written resource:", resource_written)
+                else:
+                    content_f = get_header_title(f_path)
+                content_f += get_code_tabs(pyproject["files"], out_f)
                 out_f.write(content_f)
+
             if not opt_quiet:
                 print(f"Written: {EXAMPLES_DOC}/{rst_file}")
         else: