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
Pick-to: 6.0
Change-Id: I2d11833c461d8073d2d2888576d876d3f834103a
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

1 files changed, 73 insertions, 32 deletions

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: