diff options
authorVenugopal Shivashankar <>2018-05-28 17:07:03 +0200
committerVenugopal Shivashankar <>2018-06-01 20:04:04 +0000
commit3b57289e6d8040bbb6747494bcc754bcd8751dfe (patch)
parent7f798dfc9fc6e3e9756f06f0fedc821e16f1320a (diff)
Doc: Document the tabbed browser demo
- Added docstrings to the examples sources to autogenerate the docs for the different parts. - Updated the 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 <>
-rw-r--r--sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.pngbin0 -> 51262 bytes
8 files changed, 86 insertions, 6 deletions
diff --git a/examples/webenginewidgets/tabbedbrowser/ b/examples/webenginewidgets/tabbedbrowser/
index 01a69b92..6bd2b458 100644
--- a/examples/webenginewidgets/tabbedbrowser/
+++ b/examples/webenginewidgets/tabbedbrowser/
@@ -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/ b/examples/webenginewidgets/tabbedbrowser/
index d9263be0..d85b8ad3 100644
--- a/examples/webenginewidgets/tabbedbrowser/
+++ b/examples/webenginewidgets/tabbedbrowser/
@@ -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/ b/examples/webenginewidgets/tabbedbrowser/
index 030dfc14..437c534e 100644
--- a/examples/webenginewidgets/tabbedbrowser/
+++ b/examples/webenginewidgets/tabbedbrowser/
@@ -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/ b/examples/webenginewidgets/tabbedbrowser/
index 12efdcd5..09b6cc9e 100644
--- a/examples/webenginewidgets/tabbedbrowser/
+++ b/examples/webenginewidgets/tabbedbrowser/
@@ -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()
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 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/ b/sources/pyside2/doc/
index 26d99c7e..50d2028e 100644
--- a/sources/pyside2/doc/
+++ b/sources/pyside2/doc/
@@ -18,6 +18,7 @@ import sys, os
# documentation root, use os.path.abspath to make it absolute, like shown here.
# -- 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',
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 00000000..655d6b57
--- /dev/null
+++ b/sources/pyside2/doc/tutorials/examples/images/tabbedbrowser.png
Binary files differ
diff --git a/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst b/sources/pyside2/doc/tutorials/examples/tabbedbrowser.rst
new file mode 100644
index 00000000..8a2e0311
--- /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:``
+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:``
+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:``
+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:``
+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 2e97612a..18bac57f 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
.. toctree::
:maxdepth: 2