diff options
author | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2021-03-16 22:54:01 +0100 |
---|---|---|
committer | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2021-03-17 20:58:04 +0100 |
commit | 4750fbcb8e5d1f0137a8660ffa77f595dac46504 (patch) | |
tree | e56daea9bd91ff417e73ed306df2cc6b32c3f278 | |
parent | 5c8ec34aa21469a1814682fe9b63ed79082c4661 (diff) |
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
Pick-to: 6.0
Change-Id: Id19be92e72f0a18f63b76daf1898080f3e199626
Reviewed-by: Christian Tismer <tismer@stackless.com>
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>
-rw-r--r-- | requirements.txt | 2 | ||||
-rw-r--r-- | sources/pyside6/doc/_themes/pysidedocs/static/pyside.css | 18 | ||||
-rw-r--r-- | sources/pyside6/doc/conf.py.in | 9 | ||||
-rw-r--r-- | sources/pyside6/doc/contents.rst | 4 | ||||
-rw-r--r-- | sources/pyside6/doc/deployment.rst | 2 | ||||
-rw-r--r-- | sources/pyside6/doc/gettingstarted.rst | 6 | ||||
-rw-r--r-- | sources/pyside6/doc/index.rst | 120 | ||||
-rw-r--r-- | sources/shiboken6/doc/_themes/pysidedocs/static/pyside.css | 18 | ||||
-rw-r--r-- | tools/example_gallery/main.py | 79 |
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 9b274fa1f..55726f21a 100644 --- a/sources/pyside6/doc/conf.py.in +++ b/sources/pyside6/doc/conf.py.in @@ -29,10 +29,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: |