From d97aedf37809c479ab409c4247b60c0cfcef35d6 Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Tue, 16 Mar 2021 23:39:14 +0100 Subject: doc: migrate qdoc approach to document examples There were two previous documented examples using the approach based on qdoc: stardelegate, and classwizard. This patch moves them into the 'doc/' directory for each example, and partially revert the changes from 308157f01260c640e21f6972619d3b380c007acb Additionally, an unrelated screenshot was moved to a new general 'images/' directory. Task-number: PYSIDE-1112 Pick-to: 6.0 Change-Id: I239a24fa4e4f970540857ba8b33b9b13c18142b1 Reviewed-by: Christian Tismer --- .../tabbedbrowser/doc/tabbedbrowser.png | Bin 0 -> 37147 bytes .../tabbedbrowser/doc/tabbedbrowser.rst | 58 +++++++++++++++++++++ .../dialogs/classwizard/doc/classwizard.png | Bin 0 -> 57931 bytes .../dialogs/classwizard/doc/classwizard.rst | 11 ++++ .../itemviews/stardelegate/doc/stardelegate.png | Bin 0 -> 22482 bytes .../itemviews/stardelegate/doc/stardelegate.rst | 10 ++++ sources/pyside6/doc/CMakeLists.txt | 5 -- sources/pyside6/doc/additionaldocs.lst | 12 ----- .../pyside6/doc/examples/images/tabbedbrowser.png | Bin 37147 -> 0 bytes sources/pyside6/doc/examples/tabbedbrowser.rst | 58 --------------------- sources/pyside6/doc/images/screenshot_hello.png | Bin 0 -> 21193 bytes sources/pyside6/doc/pyside-examples/examples.qdoc | 37 ------------- .../images/pysideexample-classwizard.png | Bin 57931 -> 0 bytes .../images/pysideexample-stardelegate.png | Bin 22482 -> 0 bytes .../pyside-examples/images/screenshot_hello.png | Bin 21193 -> 0 bytes .../doc/pyside-examples/pyside-classwizard.qdoc | 39 -------------- .../doc/pyside-examples/pyside-stardelegate.qdoc | 39 -------------- .../doc/qtmodules/pyside-examples.qdocconf.in | 12 ----- sources/pyside6/doc/quickstart.rst | 2 +- tools/example_gallery/main.py | 8 --- 20 files changed, 80 insertions(+), 211 deletions(-) create mode 100644 examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.png create mode 100644 examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.rst create mode 100644 examples/widgets/dialogs/classwizard/doc/classwizard.png create mode 100644 examples/widgets/dialogs/classwizard/doc/classwizard.rst create mode 100644 examples/widgets/itemviews/stardelegate/doc/stardelegate.png create mode 100644 examples/widgets/itemviews/stardelegate/doc/stardelegate.rst delete mode 100644 sources/pyside6/doc/examples/images/tabbedbrowser.png delete mode 100644 sources/pyside6/doc/examples/tabbedbrowser.rst create mode 100644 sources/pyside6/doc/images/screenshot_hello.png delete mode 100644 sources/pyside6/doc/pyside-examples/examples.qdoc delete mode 100644 sources/pyside6/doc/pyside-examples/images/pysideexample-classwizard.png delete mode 100644 sources/pyside6/doc/pyside-examples/images/pysideexample-stardelegate.png delete mode 100644 sources/pyside6/doc/pyside-examples/images/screenshot_hello.png delete mode 100644 sources/pyside6/doc/pyside-examples/pyside-classwizard.qdoc delete mode 100644 sources/pyside6/doc/pyside-examples/pyside-stardelegate.qdoc delete mode 100644 sources/pyside6/doc/qtmodules/pyside-examples.qdocconf.in diff --git a/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.png b/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.png new file mode 100644 index 000000000..27c3daa09 Binary files /dev/null and b/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.png differ diff --git a/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.rst b/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.rst new file mode 100644 index 000000000..d8f5deb8d --- /dev/null +++ b/examples/webenginewidgets/tabbedbrowser/doc/tabbedbrowser.rst @@ -0,0 +1,58 @@ +********************** +Web Browser Example +********************** + +The example demonstrates the power and simplicity offered by |project| to developers. +It uses several |pymodname| submodules to offer a fluid and modern-looking UI that +is apt for a web browser. The application offers the following features: + + * Tab-based browsing experience using QTabWidget. + * Download manager using a QProgressBar and QWebEngineDownloadItem. + * Bookmark manager using QTreeView. + +.. image:: tabbedbrowser.png + +The application's code is organized in several parts for ease of maintenance. For example, +:code:`DownloadWidget` provides a widget to track progress of a download item. In the following +sections, these different parts are discussed briefly to help you understand the Python code behind +them a little better. + +BookmarkWidget or :code:`bookmarkwidget.py` +=========================================== + +This widget docks to the left of the main window by default. It inherits QTreeView and +loads a default set of bookmarks using a QStandardItemModel. The model is populated at startup +from a JSON file, which is updated when you add or remove bookmarks from the tree view. + +.. automodule:: bookmarkwidget + :members: + +DownloadWidget or :code:`downloadwidget.py` +============================================= + +The widget tracks progress of the download item. It inherits QProgressBar to display +progress of the QWebEngineDownloadItem instance, and offers a context-menu with actions such as Launch, +Show in folder, Cancel, and Remove. + +.. automodule:: downloadwidget + :members: + +BrowserTabWidget or :code:`browsertabwidget.py` +=============================================== + +The widget includes a QWebEngineView to enable viewing web content. It docks to the right +of BookmarkWidget in the main window. + +.. automodule:: browsertabwidget + :members: + +MainWindow or :code:`main.py` +============================= + +This is the parent window that collates all the other widgets together to offer the complete package. + +.. automodule:: main + :members: + + +Try running the example to explore it further. diff --git a/examples/widgets/dialogs/classwizard/doc/classwizard.png b/examples/widgets/dialogs/classwizard/doc/classwizard.png new file mode 100644 index 000000000..1706772d8 Binary files /dev/null and b/examples/widgets/dialogs/classwizard/doc/classwizard.png differ diff --git a/examples/widgets/dialogs/classwizard/doc/classwizard.rst b/examples/widgets/dialogs/classwizard/doc/classwizard.rst new file mode 100644 index 000000000..a6959c6e2 --- /dev/null +++ b/examples/widgets/dialogs/classwizard/doc/classwizard.rst @@ -0,0 +1,11 @@ +Classwizard Example +=================== + +Demonstrates the use of QDialog in a wizard application + +This example demonstrates the use a custom QDialog in a wizard, +which generates necessary C++ class template code. + +.. image:: classwizard.png + :width: 400 + :alt: classwizard screenshot diff --git a/examples/widgets/itemviews/stardelegate/doc/stardelegate.png b/examples/widgets/itemviews/stardelegate/doc/stardelegate.png new file mode 100644 index 000000000..343416397 Binary files /dev/null and b/examples/widgets/itemviews/stardelegate/doc/stardelegate.png differ diff --git a/examples/widgets/itemviews/stardelegate/doc/stardelegate.rst b/examples/widgets/itemviews/stardelegate/doc/stardelegate.rst new file mode 100644 index 000000000..fe8a2732a --- /dev/null +++ b/examples/widgets/itemviews/stardelegate/doc/stardelegate.rst @@ -0,0 +1,10 @@ +Star Delegate Example +===================== + +Demonstrates Qt's itemview architecture + +This example demonstrates the Qt model view architecture. + +.. image:: stardelegate.png + :width: 400 + :alt: Star Delegate Screenshot diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt index 634ebb252..a8d81a772 100644 --- a/sources/pyside6/doc/CMakeLists.txt +++ b/sources/pyside6/doc/CMakeLists.txt @@ -97,11 +97,6 @@ if (FULLDOCSBUILD) endif() endforeach() - #Appending the additional qdocconf that describes the pyside-examples - #doc project. - configure_file("qtmodules/pyside-examples.qdocconf.in" "${CMAKE_CURRENT_LIST_DIR}/qtmodules/pyside-examples.qdocconf" @ONLY) - file(APPEND "pyside.qdocconf.in" "\@CMAKE_CURRENT_LIST_DIR\@/qtmodules/pyside-examples.qdocconf\n") - set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n\n") file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}") diff --git a/sources/pyside6/doc/additionaldocs.lst b/sources/pyside6/doc/additionaldocs.lst index e6ffe7e5d..037cb60f7 100644 --- a/sources/pyside6/doc/additionaldocs.lst +++ b/sources/pyside6/doc/additionaldocs.lst @@ -51,18 +51,6 @@ # fi # done # A line enclosed in [] denotes a (relative) target directory -[pyside-examples] -all-pyside-examples.webxml -pysideexamples-widgets-dialogs-classwizard-classwizard-pyproject.webxml -pysideexamples-widgets-dialogs-classwizard-classwizard-py.webxml -pysideexamples-widgets-dialogs-classwizard-classwizard-qrc.webxml -pysideexamples-widgets-dialogs-classwizard-classwizard-rc-py.webxml -pysideexamples-widgets-dialogs-classwizard-example.webxml -pysideexamples-widgets-itemviews-stardelegate-example.webxml -pysideexamples-widgets-itemviews-stardelegate-stardelegate-pyproject.webxml -pysideexamples-widgets-itemviews-stardelegate-stardelegate-py.webxml -pysideexamples-widgets-itemviews-stardelegate-stareditor-py.webxml -pysideexamples-widgets-itemviews-stardelegate-starrating-py.webxml [overviews] animation-overview.webxml diff --git a/sources/pyside6/doc/examples/images/tabbedbrowser.png b/sources/pyside6/doc/examples/images/tabbedbrowser.png deleted file mode 100644 index 27c3daa09..000000000 Binary files a/sources/pyside6/doc/examples/images/tabbedbrowser.png and /dev/null differ diff --git a/sources/pyside6/doc/examples/tabbedbrowser.rst b/sources/pyside6/doc/examples/tabbedbrowser.rst deleted file mode 100644 index c34c50647..000000000 --- a/sources/pyside6/doc/examples/tabbedbrowser.rst +++ /dev/null @@ -1,58 +0,0 @@ -********************** -Web Browser Example -********************** - -The example demonstrates the power and simplicity offered by |project| to developers. -It uses several |pymodname| submodules to offer a fluid and modern-looking UI that -is apt for a web browser. The application offers the following features: - - * Tab-based browsing experience using QTabWidget. - * Download manager using a QProgressBar and QWebEngineDownloadItem. - * Bookmark manager using QTreeView. - -.. image:: images/tabbedbrowser.png - -The application's code is organized in several parts for ease of maintenance. For example, -:code:`DownloadWidget` provides a widget to track progress of a download item. In the following -sections, these different parts are discussed briefly to help you understand the Python code behind -them a little better. - -BookmarkWidget or :code:`bookmarkwidget.py` -=========================================== - -This widget docks to the left of the main window by default. It inherits QTreeView and -loads a default set of bookmarks using a QStandardItemModel. The model is populated at startup -from a JSON file, which is updated when you add or remove bookmarks from the tree view. - -.. automodule:: bookmarkwidget - :members: - -DownloadWidget or :code:`downloadwidget.py` -============================================= - -The widget tracks progress of the download item. It inherits QProgressBar to display -progress of the QWebEngineDownloadItem instance, and offers a context-menu with actions such as Launch, -Show in folder, Cancel, and Remove. - -.. automodule:: downloadwidget - :members: - -BrowserTabWidget or :code:`browsertabwidget.py` -=============================================== - -The widget includes a QWebEngineView to enable viewing web content. It docks to the right -of BookmarkWidget in the main window. - -.. automodule:: browsertabwidget - :members: - -MainWindow or :code:`main.py` -============================= - -This is the parent window that collates all the other widgets together to offer the complete package. - -.. automodule:: main - :members: - - -Try running the example to explore it further. diff --git a/sources/pyside6/doc/images/screenshot_hello.png b/sources/pyside6/doc/images/screenshot_hello.png new file mode 100644 index 000000000..41ebbf01b Binary files /dev/null and b/sources/pyside6/doc/images/screenshot_hello.png differ diff --git a/sources/pyside6/doc/pyside-examples/examples.qdoc b/sources/pyside6/doc/pyside-examples/examples.qdoc deleted file mode 100644 index 116ed65bb..000000000 --- a/sources/pyside6/doc/pyside-examples/examples.qdoc +++ /dev/null @@ -1,37 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \group all-pyside-examples - \title All Qt for Python Examples - \brief A varied selection of examples can be found in the 'examples' directory of the - pyside-setup repository. This can be accessed after installing - PySide6 via pip, checking the 'site-packages/PySide6/examples' directory. - - This page aims to document the most important use cases of the module - and it will be extended with each release. -*/ diff --git a/sources/pyside6/doc/pyside-examples/images/pysideexample-classwizard.png b/sources/pyside6/doc/pyside-examples/images/pysideexample-classwizard.png deleted file mode 100644 index 1706772d8..000000000 Binary files a/sources/pyside6/doc/pyside-examples/images/pysideexample-classwizard.png and /dev/null differ diff --git a/sources/pyside6/doc/pyside-examples/images/pysideexample-stardelegate.png b/sources/pyside6/doc/pyside-examples/images/pysideexample-stardelegate.png deleted file mode 100644 index 343416397..000000000 Binary files a/sources/pyside6/doc/pyside-examples/images/pysideexample-stardelegate.png and /dev/null differ diff --git a/sources/pyside6/doc/pyside-examples/images/screenshot_hello.png b/sources/pyside6/doc/pyside-examples/images/screenshot_hello.png deleted file mode 100644 index 41ebbf01b..000000000 Binary files a/sources/pyside6/doc/pyside-examples/images/screenshot_hello.png and /dev/null differ diff --git a/sources/pyside6/doc/pyside-examples/pyside-classwizard.qdoc b/sources/pyside6/doc/pyside-examples/pyside-classwizard.qdoc deleted file mode 100644 index edfd68fd5..000000000 --- a/sources/pyside6/doc/pyside-examples/pyside-classwizard.qdoc +++ /dev/null @@ -1,39 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example widgets/dialogs/classwizard - \title PySide6.QtWidgets - Classwizard Example - \ingroup all-pyside-examples - \brief Demonstrates the use of QDialog in a wizard application - - This example demonstrates the use a custom QDialog in a wizard, - which generates necessary C++ class template code. - - \image pysideexample-classwizard.png - -*/ diff --git a/sources/pyside6/doc/pyside-examples/pyside-stardelegate.qdoc b/sources/pyside6/doc/pyside-examples/pyside-stardelegate.qdoc deleted file mode 100644 index 6251ff3e1..000000000 --- a/sources/pyside6/doc/pyside-examples/pyside-stardelegate.qdoc +++ /dev/null @@ -1,39 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2019 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \example widgets/itemviews/stardelegate - \title PySide6.QtWidgets - Star Delegate Example - \ingroup all-pyside-examples - \brief Demonstrates Qt's itemview architecture - - This example demonstrates the itemview architecture, which - is unique to Qt. - - \image pysideexample-stardelegate.png -*/ - diff --git a/sources/pyside6/doc/qtmodules/pyside-examples.qdocconf.in b/sources/pyside6/doc/qtmodules/pyside-examples.qdocconf.in deleted file mode 100644 index 349c7f0f7..000000000 --- a/sources/pyside6/doc/qtmodules/pyside-examples.qdocconf.in +++ /dev/null @@ -1,12 +0,0 @@ -include(@QT_SRC_DIR@/doc/global/qt-module-defaults.qdocconf) - -project = PysideExamples -description = Qt for Python Examples -version = $QT_VERSION - -sourcedirs += @CMAKE_CURRENT_SOURCE_DIR@/pyside-examples -exampledirs = @CMAKE_CURRENT_SOURCE_DIR@/../../../examples -examples.fileextensions += *.py *.pyproject -imagedirs += @CMAKE_CURRENT_SOURCE_DIR@/pyside-examples/images -url.examples = "https://code.qt.io/cgit/pyside/pyside-setup.git/tree/examples/\1?h=$QT_VER" -include(../pyside-config.qdocconf) diff --git a/sources/pyside6/doc/quickstart.rst b/sources/pyside6/doc/quickstart.rst index 14d1c03a0..8cdd46053 100644 --- a/sources/pyside6/doc/quickstart.rst +++ b/sources/pyside6/doc/quickstart.rst @@ -116,5 +116,5 @@ guide you through the development process: Try clicking the button at the bottom to see which greeting you get. - .. image:: pyside-examples/images/screenshot_hello.png + .. image:: images/screenshot_hello.png :alt: Hello World application diff --git a/tools/example_gallery/main.py b/tools/example_gallery/main.py index 0ec5f9f66..a55e0f27b 100644 --- a/tools/example_gallery/main.py +++ b/tools/example_gallery/main.py @@ -267,14 +267,6 @@ if __name__ == "__main__": A collection of examples are provided with |project| to help new users to understand different use cases of the module. - .. toctree:: - :maxdepth: 1 - - tabbedbrowser.rst - - Gallery - ------- - You can find all these examples inside the ``pyside-setup`` on the ``examples`` directory, or you can access them after installing |pymodname| from ``pip`` inside the ``site-packages/PySide6/examples`` directory. -- cgit v1.2.3