doc: example gallery show code in tabs

Before this patch, the auto-generated documentation page
had all the files from the .pyproject listed one after the other.
This uses a new sphinx extension called sphinx-tabs

    https://github.com/executablebooks/sphinx-tabs

which allows us to easily add content in tabs.

Task-number: PYSIDE-1112
Change-Id: Ibd66a8c911f05be13ae2700be6d3e95a2b98b775
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit a7c7c729a388b0a4e0e104fac1130feb6e03151b)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

3 files changed, 47 insertions, 15 deletions

diff --git a/requirements.txt b/requirements.txt
index dd4b6cc8e..2f60cb9ee 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,5 +1,6 @@
 setuptools
 sphinx
+sphinx-tabs
 six
 wheel>=0.35
 PyOpenGL
diff --git a/sources/pyside6/doc/conf.py.in b/sources/pyside6/doc/conf.py.in
index 5a034f465..45df12344 100644
--- a/sources/pyside6/doc/conf.py.in
+++ b/sources/pyside6/doc/conf.py.in
@@ -29,7 +29,8 @@ if @HAS_WEBENGINE_WIDGETS@:
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.ifconfig',
 'sphinx.ext.coverage', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
 'sphinx.ext.graphviz', 'inheritance_diagram', 'pysideinclude',
-'sphinx.ext.viewcode']
+'sphinx.ext.viewcode',
+'sphinx_tabs.tabs']
 
 output_format='@DOC_OUTPUT_FORMAT@'
 
diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py
index afacab628..4a20760b7 100644
--- a/tools/example_gallery/main.py
+++ b/tools/example_gallery/main.py
@@ -38,7 +38,7 @@
 ###############
 
 
-DESCRIPTION = """
+"""
 This tool reads all the examples from the main repository that have a
 '.pyproject' file, and generates a special table/gallery in the documentation
 page.
@@ -56,6 +56,14 @@ from textwrap import dedent
 
 
 opt_quiet = False
+suffixes = {
+    ".py": "py",
+    ".qml": "js",
+    ".conf": "ini",
+    ".qrc": "xml",
+    ".ui": "xml",
+    ".xbel": "xml",
+}
 
 
 def ind(x):
@@ -68,6 +76,12 @@ def get_colgroup(columns, indent=2):
     return f'{ind(indent)}<col style="width: {width_column}%" />\n' * columns
 
 
+def get_lexer(suffix):
+    if suffix in suffixes:
+        return suffixes[suffix]
+    return "text"
+
+
 def add_indent(s, level):
     new_s = ""
     for line in s.splitlines():
@@ -84,7 +98,8 @@ def get_module_gallery(examples):
     information, from one specific module.
     """
 
-    gallery = dedent(f"""\
+    gallery = dedent(
+        f"""\
     <table class="special">
         <colgroup>
 {get_colgroup(columns, indent=3)}
@@ -116,7 +131,8 @@ def get_module_gallery(examples):
                 gallery += f'{ind(2)}<td style="display: none;"></td>\n'
         gallery += f"{ind(1)}</tr>\n"
 
-    gallery += dedent("""\
+    gallery += dedent(
+        """\
     </table>
     """
     )
@@ -137,13 +153,12 @@ if __name__ == "__main__":
     DIR = Path(__file__).parent
     EXAMPLES_DOC = f"{DIR}/../../sources/pyside6/doc/examples"
     EXAMPLES_DIR = Path(f"{DIR}/../../examples/")
+    BASE_URL = "https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples"
     columns = 5
     gallery = ""
 
-    parser = ArgumentParser(description=DESCRIPTION,
-                            formatter_class=RawTextHelpFormatter)
-    parser.add_argument('--quiet', '-q', action='store_true',
-                        help='Quiet')
+    parser = ArgumentParser(description=__doc__, formatter_class=RawTextHelpFormatter)
+    parser.add_argument("--quiet", "-q", action="store_true", help="Quiet")
     options = parser.parse_args()
     opt_quiet = options.quiet
 
@@ -185,22 +200,35 @@ if __name__ == "__main__":
 
         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 project_file in pyproject["files"]:
-                    if project_file.split(".")[-1] in ("png", "pyc"):
+                for i, project_file in enumerate(pyproject["files"]):
+                    pfile = Path(project_file)
+                    if pfile.suffix in (".png", ".pyc"):
                         continue
-                    length = len(project_file)
-                    content_f += f"{project_file}\n{'=' * length}\n\n::\n\n"
+
+                    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, 1)
+                    content_f += add_indent(_content, 2)
                     content_f += "\n\n"
                 out_f.write(content_f)
             if not opt_quiet:
@@ -209,7 +237,8 @@ if __name__ == "__main__":
             if not opt_quiet:
                 print("Empty '.pyproject' file, skipping")
 
-    base_content = dedent("""\
+    base_content = dedent(
+        """\
     ..
         This file was auto-generated from the 'pyside-setup/tools/example_gallery'
         All editions in this file will be lost.
@@ -243,7 +272,8 @@ if __name__ == "__main__":
     # for them will be able to, since they are indexed.
     # Notice that :hidden: will not add the list of files by the end of the
     # main examples HTML page.
-    footer_index = dedent("""\
+    footer_index = dedent(
+        """\
       .. toctree::
          :hidden:
          :maxdepth: 1