From 3b57289e6d8040bbb6747494bcc754bcd8751dfe Mon Sep 17 00:00:00 2001 From: Venugopal Shivashankar Date: Mon, 28 May 2018 17:07:03 +0200 Subject: Doc: Document the tabbed browser demo - Added docstrings to the examples sources to autogenerate the docs for the different parts. - Updated the conf.py.in to include sphinx.ext.viewcode to generate html for every source file of the example. Change-Id: I668c55070556ca49d12d38c8ec83f09313bffc36 Reviewed-by: Cristian Maureira-Fredes Reviewed-by: Paul Wicking Reviewed-by: Friedemann Kleint --- .../tabbedbrowser/bookmarkwidget.py | 1 + .../tabbedbrowser/browsertabwidget.py | 1 + .../tabbedbrowser/downloadwidget.py | 2 +- examples/webenginewidgets/tabbedbrowser/main.py | 6 ++- sources/pyside2/doc/conf.py.in | 4 +- .../tutorials/examples/images/tabbedbrowser.png | Bin 0 -> 51262 bytes .../doc/tutorials/examples/tabbedbrowser.rst | 57 +++++++++++++++++++++ sources/pyside2/doc/tutorials/index.rst | 21 ++++++-- 8 files changed, 86 insertions(+), 6 deletions(-) create mode 100644 sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.png create mode 100644 sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst diff --git a/examples/webenginewidgets/tabbedbrowser/bookmarkwidget.py b/examples/webenginewidgets/tabbedbrowser/bookmarkwidget.py index 01a69b921..6bd2b4586 100644 --- a/examples/webenginewidgets/tabbedbrowser/bookmarkwidget.py +++ b/examples/webenginewidgets/tabbedbrowser/bookmarkwidget.py @@ -122,6 +122,7 @@ def _serialize_model(model, directory): # Bookmarks as a tree view to be used in a dock widget with # functionality to persist and populate tool bars and menus. class BookmarkWidget(QTreeView): + """Provides a tree view to manage the bookmarks.""" open_bookmark = QtCore.Signal(QUrl) open_bookmark_in_new_tab = QtCore.Signal(QUrl) diff --git a/examples/webenginewidgets/tabbedbrowser/browsertabwidget.py b/examples/webenginewidgets/tabbedbrowser/browsertabwidget.py index d9263be08..d85b8ad3d 100644 --- a/examples/webenginewidgets/tabbedbrowser/browsertabwidget.py +++ b/examples/webenginewidgets/tabbedbrowser/browsertabwidget.py @@ -50,6 +50,7 @@ from PySide2.QtWebEngineWidgets import (QWebEngineDownloadItem, QWebEnginePage, QWebEngineProfile) class BrowserTabWidget(QTabWidget): + """Enables having several tabs with QWebEngineView.""" url_changed = QtCore.Signal(QUrl) enabled_changed = QtCore.Signal(QWebEnginePage.WebAction, bool) diff --git a/examples/webenginewidgets/tabbedbrowser/downloadwidget.py b/examples/webenginewidgets/tabbedbrowser/downloadwidget.py index 030dfc14b..437c534ec 100644 --- a/examples/webenginewidgets/tabbedbrowser/downloadwidget.py +++ b/examples/webenginewidgets/tabbedbrowser/downloadwidget.py @@ -48,7 +48,7 @@ from PySide2.QtWebEngineWidgets import QWebEngineDownloadItem # A QProgressBar with context menu for displaying downloads in a QStatusBar. class DownloadWidget(QProgressBar): - + """Lets you track progress of a QWebEngineDownloadItem.""" finished = QtCore.Signal() remove_requested = QtCore.Signal() diff --git a/examples/webenginewidgets/tabbedbrowser/main.py b/examples/webenginewidgets/tabbedbrowser/main.py index 12efdcd5c..09b6cc9ec 100644 --- a/examples/webenginewidgets/tabbedbrowser/main.py +++ b/examples/webenginewidgets/tabbedbrowser/main.py @@ -60,6 +60,7 @@ from PySide2.QtWebEngineWidgets import (QWebEngineDownloadItem, QWebEnginePage, main_windows = [] def create_main_window(): + """Creates a MainWindow using 75% of the available screen resolution.""" main_win = MainWindow() main_windows.append(main_win) available_geometry = app.desktop().availableGeometry(main_win) @@ -68,11 +69,14 @@ def create_main_window(): return main_win def create_main_window_with_browser(): + """Creates a MainWindow with a tab that loads the www.qt.io webpage.""" main_win = create_main_window() return main_win.add_browser_tab() class MainWindow(QMainWindow): - + """Provides the parent window that includes the BookmarkWidget, + BrowserTabWidget, and a DownloadWidget, to offer the complete + web browsing experience.""" def __init__(self): super(MainWindow, self).__init__() diff --git a/sources/pyside2/doc/conf.py.in b/sources/pyside2/doc/conf.py.in index 26d99c7ed..50d2028e7 100644 --- a/sources/pyside2/doc/conf.py.in +++ b/sources/pyside2/doc/conf.py.in @@ -18,6 +18,7 @@ import sys, os # documentation root, use os.path.abspath to make it absolute, like shown here. sys.path.append('@CMAKE_CURRENT_SOURCE_DIR@') sys.path.append('@pyside_BINARY_DIR@') +sys.path.append('@CMAKE_CURRENT_SOURCE_DIR@/../../../examples/webenginewidgets/tabbedbrowser') # -- General configuration ----------------------------------------------------- @@ -26,7 +27,8 @@ sys.path.append('@pyside_BINARY_DIR@') #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.graphviz', 'inheritance_diagram', 'pysideinclude', +'sphinx.ext.viewcode'] rst_epilog = """ .. |project| replace:: Qt for Python diff --git a/sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.png b/sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.png new file mode 100644 index 000000000..655d6b57f Binary files /dev/null and b/sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.png differ diff --git a/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst b/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst new file mode 100644 index 000000000..8a2e03110 --- /dev/null +++ b/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst @@ -0,0 +1,57 @@ +********************** +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 is a widget that 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 +for a JSON file, which is updated when you add or remove bookmarks from the tree view. + +.. automodule:: bookmarkwidget + :members: + +DownloadWidget or :code:`downloadwidget.py` +============================================= + +This is a widget that 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` +=============================================== + +This is a widget that includes a QWebEngineView to enable viewing web pages. 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/pyside2/doc/tutorials/index.rst b/sources/pyside2/doc/tutorials/index.rst index 2e97612aa..18bac57fd 100644 --- a/sources/pyside2/doc/tutorials/index.rst +++ b/sources/pyside2/doc/tutorials/index.rst @@ -1,7 +1,22 @@ -PySide tutorials -**************** +PySide examples and tutorials +***************************** -A collection of tutorials and "walkthrough" guides are provided with PySide to help new users get started with PySide development. These documents were ported from C++ to Python and cover a range of topics, from basic use of widgets to step-by-step tutorials that show how an application is put together. +A collection of examples and tutorials with "walkthrough" guides are +provided with |project| to help new users get started. These +documents were ported from C++ to Python and cover a range of topics, +from basic use of widgets to step-by-step tutorials that show how an +application is put together. + +Examples and demos +=================== + +.. toctree:: + :maxdepth: 1 + + examples/tabbedbrowser.rst + +Tutorials +========== .. toctree:: :maxdepth: 2 -- cgit v1.2.3