Doc: Set up necessary infra. for example doc generation

Qdoc must be made aware of the .py and .pyproject file types
to generate the example page. In addition, it needs the URL to
the example on https://code.qt.io/pyside-setup.git to link.

Change-Id: I824898831475b6fe3f66df0cd16df62a9301a69d
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>

10 files changed, 145 insertions, 1 deletions

diff --git a/sources/pyside2/CMakeLists.txt b/sources/pyside2/CMakeLists.txt
index 16038594a..1efcb53ed 100644
--- a/sources/pyside2/CMakeLists.txt
+++ b/sources/pyside2/CMakeLists.txt
@@ -179,6 +179,7 @@ string(REGEX MATCHALL "[0-9]+" qt_version_helper "${Qt5Core_VERSION}")
 
 list(GET qt_version_helper 0 QT_VERSION_MAJOR)
 list(GET qt_version_helper 1 QT_VERSION_MINOR)
+list(GET qt_version_helper 2 QT_VERSION_PATCH)
 unset(qt_version_helper)
 
 set(PYSIDE_QT_VERSION "${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}" CACHE STRING "Qt version used to compile PySide" FORCE)
diff --git a/sources/pyside2/doc/CMakeLists.txt b/sources/pyside2/doc/CMakeLists.txt
index 36f770367..9d5a5a0a8 100644
--- a/sources/pyside2/doc/CMakeLists.txt
+++ b/sources/pyside2/doc/CMakeLists.txt
@@ -70,6 +70,11 @@ foreach(moduleIn ${all_module_shortnames})
     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</typesystem>\n")
 file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}")
 
@@ -82,7 +87,10 @@ set(QDOC_TYPESYSTEM_PATH "${pyside2_SOURCE_DIR}${PATH_SEP}${pyside2_BINARY_DIR}"
 
 add_custom_target(qdoc
                 # Use dummy Qt version information, QDoc needs it but has no effect on WebXML output
-                COMMAND ${CMAKE_COMMAND} -E env BUILDDIR=${CMAKE_CURRENT_LIST_DIR}/src QT_INSTALL_DOCS=${QT_SRC_DIR}/doc QT_VERSION=1.0.0 QT_VER=1.0 QT_VERSION_TAG=100
+                COMMAND ${CMAKE_COMMAND} -E env BUILDDIR=${CMAKE_CURRENT_LIST_DIR}/src QT_INSTALL_DOCS=${QT_SRC_DIR}/doc
+                QT_VERSION=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}.${QT_VERSION_PATCH}
+                QT_VER=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}
+                QT_VERSION_TAG=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}.${QT_VERSION_PATCH}
                 qdoc pyside.qdocconf -single-exec -installdir ${DOC_DATA_DIR} -outputdir ${DOC_DATA_DIR}
                 COMMENT "Running qdoc against Qt source code..."
                 SOURCE "pyside.qdocconf")
diff --git a/sources/pyside2/doc/additionaldocs.lst b/sources/pyside2/doc/additionaldocs.lst
index 037cb60f7..44c562424 100644
--- a/sources/pyside2/doc/additionaldocs.lst
+++ b/sources/pyside2/doc/additionaldocs.lst
@@ -51,6 +51,18 @@
 #     fi
 # done
 # A line enclosed in [] denotes a (relative) target directory
+[pyside-examples]
+all-pyside-examples.webxml
+pyside2examples-widgets-dialogs-classwizard-classwizard-pyproject.webxml
+pyside2examples-widgets-dialogs-classwizard-classwizard-py.webxml
+pyside2examples-widgets-dialogs-classwizard-classwizard-qrc.webxml
+pyside2examples-widgets-dialogs-classwizard-classwizard-rc-py.webxml
+pyside2examples-widgets-dialogs-classwizard-example.webxml
+pyside2examples-widgets-itemviews-stardelegate-example.webxml
+pyside2examples-widgets-itemviews-stardelegate-stardelegate-pyproject.webxml
+pyside2examples-widgets-itemviews-stardelegate-stardelegate-py.webxml
+pyside2examples-widgets-itemviews-stardelegate-stareditor-py.webxml
+pyside2examples-widgets-itemviews-stardelegate-starrating-py.webxml
 
 [overviews]
 animation-overview.webxml
diff --git a/sources/pyside2/doc/pyside-examples/examples.qdoc b/sources/pyside2/doc/pyside-examples/examples.qdoc
new file mode 100644
index 000000000..d82b33cf7
--- /dev/null
+++ b/sources/pyside2/doc/pyside-examples/examples.qdoc
@@ -0,0 +1,32 @@
+/****************************************************************************
+**
+** 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 list of all the examples that are available with the Qt for Python package.
+*/
diff --git a/sources/pyside2/doc/pyside-examples/images/pyside2example-classwizard.png b/sources/pyside2/doc/pyside-examples/images/pyside2example-classwizard.png
new file mode 100644
index 000000000..1706772d8
--- /dev/null
+++ b/sources/pyside2/doc/pyside-examples/images/pyside2example-classwizard.png
diff --git a/sources/pyside2/doc/pyside-examples/images/pyside2example-stardelegate.png b/sources/pyside2/doc/pyside-examples/images/pyside2example-stardelegate.png
new file mode 100644
index 000000000..343416397
--- /dev/null
+++ b/sources/pyside2/doc/pyside-examples/images/pyside2example-stardelegate.png
diff --git a/sources/pyside2/doc/pyside-examples/pyside2-classwizard.qdoc b/sources/pyside2/doc/pyside-examples/pyside2-classwizard.qdoc
new file mode 100644
index 000000000..02560889b
--- /dev/null
+++ b/sources/pyside2/doc/pyside-examples/pyside2-classwizard.qdoc
@@ -0,0 +1,39 @@
+/****************************************************************************
+**
+** 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 PySide2.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 pyside2example-classwizard.png
+
+*/
diff --git a/sources/pyside2/doc/pyside-examples/pyside2-stardelegate.qdoc b/sources/pyside2/doc/pyside-examples/pyside2-stardelegate.qdoc
new file mode 100644
index 000000000..9df718335
--- /dev/null
+++ b/sources/pyside2/doc/pyside-examples/pyside2-stardelegate.qdoc
@@ -0,0 +1,39 @@
+/****************************************************************************
+**
+** 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 PySide2.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 pyside2example-stardelegate.png
+*/
+
diff --git a/sources/pyside2/doc/qtmodules/pyside-examples.qdocconf.in b/sources/pyside2/doc/qtmodules/pyside-examples.qdocconf.in
new file mode 100644
index 000000000..14808f218
--- /dev/null
+++ b/sources/pyside2/doc/qtmodules/pyside-examples.qdocconf.in
@@ -0,0 +1,12 @@
+include(@QT_SRC_DIR@/doc/global/qt-module-defaults.qdocconf)
+
+project = Pyside2Examples
+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/pyside2/doc/tutorials/index.rst b/sources/pyside2/doc/tutorials/index.rst
index 33ac5825e..5b8fe9361 100644
--- a/sources/pyside2/doc/tutorials/index.rst
+++ b/sources/pyside2/doc/tutorials/index.rst
@@ -14,6 +14,7 @@ Examples and demos
    :maxdepth: 1
 
    examples/tabbedbrowser.rst
+   ../pyside-examples/all-pyside-examples.rst
 
 Tutorials
 ==========