doc: add sphinx-panels to the documentation

This plugin replaces sphinx-tabs, so that's removed.
The panels plugin will add bootstrap responsive cards to the docs
allowing us to use them instead of the ad-hoc table we had.

Additionally, this changes the example gallery tool too,
since the main gallery was built using our own table implementation.

Since Panels also provides options to add content in tabs, with CSS
instead of JS (from sphinx-tabs), we update the generated examples
files.

Fixing warning messages related to files that didn't exist,
duplicated references, and redundant indexes.

Task-number: PYSIDE-1112
Change-Id: Id19be92e72f0a18f63b76daf1898080f3e199626
Reviewed-by: Christian Tismer <tismer@stackless.com>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
(cherry picked from commit 4750fbcb8e5d1f0137a8660ffa77f595dac46504)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

9 files changed, 170 insertions, 88 deletions

diff --git a/requirements.txt b/requirements.txt
index 2f60cb9ee..97db193f4 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,6 +1,6 @@
 setuptools
 sphinx
-sphinx-tabs
+sphinx-panels
 six
 wheel>=0.35
 PyOpenGL
diff --git a/sources/pyside6/doc/_themes/pysidedocs/static/pyside.css b/sources/pyside6/doc/_themes/pysidedocs/static/pyside.css
index 6b9fe3f05..506b61d15 100644
--- a/sources/pyside6/doc/_themes/pysidedocs/static/pyside.css
+++ b/sources/pyside6/doc/_themes/pysidedocs/static/pyside.css
@@ -2158,3 +2158,21 @@ div.leftside {
 div.rightside {
     margin-left: 50%;
 }
+
+.btn-qt:hover,
+.btn-qt:active,
+.btn-qt:focus,
+.btn-qt.active {
+  background: #41cd52;
+  color: #fff !important;
+  border-color: #fff;
+}
+
+/* Using !important is not recommended, but out CSS is being added
+ * to the pages before the bootstrap ones, so we cannot override them
+ * without using it */
+.btn-qt {
+  color: #41cd52 !important;
+  border-color: #41cd52 !important;
+  font-weight: bold !important;
+}
diff --git a/sources/pyside6/doc/conf.py.in b/sources/pyside6/doc/conf.py.in
index 45df12344..c731cae81 100644
--- a/sources/pyside6/doc/conf.py.in
+++ b/sources/pyside6/doc/conf.py.in
@@ -27,10 +27,11 @@ if @HAS_WEBENGINE_WIDGETS@:
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 #extensions = ['sphinx.ext.todo', 'sphinx.ext.graphviz', 'inheritance_diagram', 'pysideinclude']
 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_tabs.tabs']
+    'sphinx.ext.coverage', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
+    'sphinx.ext.graphviz', 'inheritance_diagram', 'pysideinclude',
+    'sphinx.ext.viewcode',
+    'sphinx_panels',
+    ]
 
 output_format='@DOC_OUTPUT_FORMAT@'
 
diff --git a/sources/pyside6/doc/contents.rst b/sources/pyside6/doc/contents.rst
index bb849ce6c..b11298016 100644
--- a/sources/pyside6/doc/contents.rst
+++ b/sources/pyside6/doc/contents.rst
@@ -15,6 +15,10 @@
     licenses.rst
     modules.rst
     considerations.rst
+..
+    Intersphinx references in toctrees is not supported
+    https://github.com/sphinx-doc/sphinx/issues/1836
+..
     shiboken6/index.rst
 
 Module Index
diff --git a/sources/pyside6/doc/deployment.rst b/sources/pyside6/doc/deployment.rst
index 4d5f0185c..550273c22 100644
--- a/sources/pyside6/doc/deployment.rst
+++ b/sources/pyside6/doc/deployment.rst
@@ -1,4 +1,4 @@
-.. _deployment:
+.. _deployment-guides:
 
 |project| Deployment
 ====================
diff --git a/sources/pyside6/doc/gettingstarted.rst b/sources/pyside6/doc/gettingstarted.rst
index bfdcc92b4..e5731c4d3 100644
--- a/sources/pyside6/doc/gettingstarted.rst
+++ b/sources/pyside6/doc/gettingstarted.rst
@@ -17,10 +17,10 @@ On **Linux** you might get them with your operating system package manager, on *
 you might get them with ``brew``, and on **Windows** you can download the installer from each
 website.
 
- * **Python**: 3.6+ `[official website] <https://www.python.org/downloads/>`_
+ * **Python**: 3.6+ `[official Python website] <https://www.python.org/downloads/>`_
  * **Qt:** 6.0+ `[online installer] <https://download.qt.io/official_releases/online_installers/>`_
- * **CMake:** 3.18+ `[official website] <https://cmake.org/download/>`_
- * **Git:** 2.0+. `[official website] <https://git-scm.com/downloads>`_
+ * **CMake:** 3.18+ `[official CMake website] <https://cmake.org/download/>`_
+ * **Git:** 2.0+. `[official Git website] <https://git-scm.com/downloads>`_
  * **libclang:** The libclang library, recommended: version 10 for 6.0+.
    Prebuilt versions for each OS can be `downloaded here`_.
 
diff --git a/sources/pyside6/doc/index.rst b/sources/pyside6/doc/index.rst
index 212df0185..c982c7c3b 100644
--- a/sources/pyside6/doc/index.rst
+++ b/sources/pyside6/doc/index.rst
@@ -38,34 +38,102 @@ Documentation
 
 .. ifconfig:: output_format == 'html'
 
-    .. raw:: html
+    .. panels::
+        :body: text-center
+        :container: container-lg pb-3
+        :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2
 
-        <table class="special">
-            <colgroup>
-                <col style="width: 33%" />
-                <col style="width: 33%" />
-                <col style="width: 33%" />
-            </colgroup>
-            <tr>
-                <td><a href="quickstart.html"><p><strong>Check It Out!</strong><br/>Write your first Qt app.</p></a></td>
-                <td><a href="gettingstarted.html"><p><strong>Getting Started</strong><br/>Install and build from source.</p></a></td>
-                <td><a href="api.html"><p><strong>API Docs</strong><br/>Qt for Python API reference.</p></a></td>
-            </tr>
+        Write your first Qt application.
 
-            <tr>
-                <td><a href="tutorials/index.html"><p><strong>Tutorials</strong><br/>Learn with step-by-step guides.</p></a></td>
-                <td><a href="examples/index.html"><p><strong>Examples</strong><br/>Check all the available examples.</p></a></td>
-                <td><a href="videos.html"><p><strong>Videos</strong><br/>Watch webinars, Talks, and more.</p></a></td>
-            </tr>
+        +++
 
-            <tr>
-                <td><a href="deployment.html" style="display: block;"><p><strong>Deployment</strong><br/>Learn to deploy your apps.</p></a></td>
-                <td><a href="considerations.html" style="display: block;"><p><strong>Considerations</strong><br/>API differences and known issues.</p></a></td>
-                <td><a href="shiboken6/index.html" style="display: block;"><p><strong>Shiboken</strong><br/>Generate C++ to Python binding.</p></a></td>
-            </tr>
-        </table>
+        .. link-button:: quickstart
+            :type: ref
+            :text: Check it out!
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        Install and build from source.
+
+        +++
+
+        .. link-button:: gettingstarted
+            :type: ref
+            :text: Getting Started
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        PySide API reference.
 
-.. ifconfig :: output_format == 'qthelp'
+        +++
+
+        .. link-button:: api
+            :type: ref
+            :text: API Docs
+            :classes: btn-qt btn-block stretched-link
+
+        ---
+
+        Learn with step-by-step guides.
+
+        +++
+
+        .. link-button:: tutorials/index
+            :type: ref
+            :text: Tutorials
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        Check all the available examples.
+
+        +++
+
+        .. link-button:: examples/index
+            :type: ref
+            :text: Examples
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        Watch webinars, talks, and more.
+
+        +++
+
+        .. link-button:: videos
+            :type: ref
+            :text: Videos
+            :classes: btn-qt btn-block stretched-link
+
+        ---
+
+        Learn to deploy your applications.
+
+        +++
+
+        .. link-button:: deployment-guides
+            :type: ref
+            :text: Deployment
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        API differences and known issues.
+
+        +++
+
+        .. link-button:: considerations
+            :type: ref
+            :text: Considerations
+            :classes: btn-qt btn-block stretched-link
+        ---
+
+        Generate C++ to Python bindings.
+
+        +++
+
+        .. link-button:: shiboken6/index.html
+            :text: Shiboken
+            :classes: btn-qt btn-block stretched-link
+
+.. ifconfig:: output_format == 'qthelp'
 
     .. raw:: html
 
@@ -80,13 +148,11 @@ Documentation
                 <td><a href="gettingstarted.html"><p><strong>Getting Started</strong><br/>Install and build from source.</p></a></td>
                 <td><a href="api.html"><p><strong>API Docs</strong><br/>Qt for Python API reference.</p></a></td>
             </tr>
-
             <tr>
                 <td><a href="tutorials/index.html"><p><strong>Tutorials</strong><br/>Learn with step-by-step guides.</p></a></td>
                 <td><a href="examples/index.html"><p><strong>Examples</strong><br/>Check all the available examples.</p></a></td>
                 <td><a href="videos.html"><p><strong>Videos</strong><br/>Watch webinars, Talks, and more.</p></a></td>
             </tr>
-
             <tr>
                 <td><a href="deployment.html" style="display: block;"><p><strong>Deployment</strong><br/>Learn to deploy your apps.</p></a></td>
                 <td><a href="considerations.html" style="display: block;"><p><strong>Considerations</strong><br/>API differences and known issues.</p></a></td>
@@ -94,6 +160,7 @@ Documentation
             </tr>
         </table>
 
+
 We have also a `wiki page`_ where you can find how to report bugs, contribute or contact the community.
 
 .. _`wiki page`: https://wiki.qt.io/Qt_for_Python
@@ -104,5 +171,4 @@ We have also a `wiki page`_ where you can find how to report bugs, contribute or
 
    contents.rst
    gettingstarted*
-   pyside-examples/pysideexamples*
    overviews/*
diff --git a/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css b/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css
index 6b9fe3f05..506b61d15 100644
--- a/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css
+++ b/sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css
@@ -2158,3 +2158,21 @@ div.leftside {
 div.rightside {
     margin-left: 50%;
 }
+
+.btn-qt:hover,
+.btn-qt:active,
+.btn-qt:focus,
+.btn-qt.active {
+  background: #41cd52;
+  color: #fff !important;
+  border-color: #fff;
+}
+
+/* Using !important is not recommended, but out CSS is being added
+ * to the pages before the bootstrap ones, so we cannot override them
+ * without using it */
+.btn-qt {
+  color: #41cd52 !important;
+  border-color: #41cd52 !important;
+  font-weight: bold !important;
+}
diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py
index f1a9c4c5f..0ec5f9f66 100644
--- a/tools/example_gallery/main.py
+++ b/tools/example_gallery/main.py
@@ -71,12 +71,6 @@ def ind(x):
     return " " * 4 * x
 
 
-def get_colgroup(columns, indent=2):
-    width = 80  # percentage
-    width_column = width // columns
-    return f'{ind(indent)}<col style="width: {width_column}%" />\n' * columns
-
-
 def get_lexer(suffix):
     if suffix in suffixes:
         return suffixes[suffix]
@@ -99,45 +93,29 @@ def get_module_gallery(examples):
     information, from one specific module.
     """
 
-    gallery = dedent(
-        f"""\
-    <table class="special">
-        <colgroup>
-{get_colgroup(columns, indent=3)}
-        </colgroup>
-    """
+    gallery = (
+        ".. panels::\n"
+        f"{ind(1)}:container: container-lg pb-3\n"
+        f"{ind(1)}:column: col-lg-3 col-md-4 col-sm-6 col-xs-12 p-2\n\n"
     )
-
     # Iteration per rows
-    for i in range(math.ceil(len(examples) / columns)):
-        gallery += f"{ind(1)}<tr>\n"
-        # Iteration per columns
-        for j in range(columns):
-            # We use a 'try-except' to handle when the examples are
-            # not an exact 'rows x columns', meaning that some cells
-            # will be empty.
-            try:
-                e = examples[i * columns + j]
-                url = e["rst"].replace(".rst", ".html")
-                name = e["example"]
-                underline = f'{e["module"]}'
-                if e["extra"]:
-                    underline += f'/{e["extra"]}'
-                gallery += (
-                    f'{ind(2)}<td><a href="{url}"><p><strong>{name}</strong><br/>'
-                    f"({underline})</p></a></td>\n"
-                )
-            except IndexError:
-                # We use display:none to hide the cell
-                gallery += f'{ind(2)}<td style="display: none;"></td>\n'
-        gallery += f"{ind(1)}</tr>\n"
-
-    gallery += dedent(
-        """\
-    </table>
-    """
-    )
-    return gallery
+    for i in range(math.ceil(len(examples))):
+        e = examples[i]
+        url = e["rst"].replace(".rst", ".html")
+        name = e["example"]
+        underline = f'{e["module"]}'
+        if e["extra"]:
+            underline += f'/{e["extra"]}'
+
+        if i > 0:
+            gallery += f"{ind(1)}---\n"
+
+        gallery += f"{ind(1)}`{name} <{url}>`_\n"
+        # TODO: Use the body to add the screenshot
+        gallery += f"{ind(1)}+++\n"
+        gallery += f"{ind(1)}{underline}\n"
+
+    return f"{gallery}\n"
 
 
 def remove_licenses(s):
@@ -157,11 +135,10 @@ def get_code_tabs(files, project_file):
         if pfile.suffix in (".png", ".pyc"):
             continue
 
-        if i == 0:
-            content += ".. tabs::\n\n"
+        content += f".. tabbed:: {project_file}\n\n"
 
-        suffix = get_lexer(pfile.suffix)
-        content += add_indent(f".. code-tab:: {suffix} {project_file}", 1)
+        lexer = get_lexer(pfile.suffix)
+        content += add_indent(f".. code-block:: {lexer}", 1)
         content += "\n"
 
         _path = f_path.resolve().parents[0] / project_file
@@ -294,7 +271,6 @@ if __name__ == "__main__":
        :maxdepth: 1
 
        tabbedbrowser.rst
-       ../pyside-examples/all-pyside-examples.rst
 
     Gallery
     -------
@@ -303,8 +279,6 @@ if __name__ == "__main__":
     directory, or you can access them after installing |pymodname| from ``pip``
     inside the ``site-packages/PySide6/examples`` directory.
 
-    .. raw:: html
-
        """
     )
 
@@ -329,8 +303,9 @@ if __name__ == "__main__":
         for module_name, e in sorted(examples.items()):
             for i in e:
                 index_files.append(i["rst"])
-            f.write(f"{ind(1)}<h3>{module_name.title()}</h3>\n")
-            f.write(add_indent(get_module_gallery(e), 1))
+            f.write(f"{module_name.title()}\n")
+            f.write(f"{'*' * len(module_name.title())}\n")
+            f.write(get_module_gallery(e))
         f.write("\n\n")
         f.write(footer_index)
         for i in index_files: