Documentation build: Avoid re-running qdoc/shiboken every time

The qdoc and shiboken steps take quite a long time when
rebuilding the documentation.

Similar to the generator dependency on
mjb_rejected_classes.log (see CMake macro
create_generator_target_library_name /
sources/cmake_helpers/helpers.cmake:262)), turn the
qdoc/shiboken targets into custom commands producing specific
files (qtcore-index.webxml, QtCore/index.rst).

This prevents the commands from being re-run as long
as the files exist and are not outdated.

Adapt the documentation.

Change-Id: I00033e6f1034a5fdc534a0f2fee018268e2e482a
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit 1251fb08619e030665651ea965c1ee6c283b9913)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>

2 files changed, 39 insertions, 25 deletions

diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt
index b89d5c5e4..634ebb252 100644
--- a/sources/pyside6/doc/CMakeLists.txt
+++ b/sources/pyside6/doc/CMakeLists.txt
@@ -112,15 +112,16 @@ if (FULLDOCSBUILD)
 
     set(QDOC_TYPESYSTEM_PATH "${pyside6_SOURCE_DIR}${PATH_SEP}${pyside6_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=${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")
+    add_custom_target(qdoc DEPENDS "${DOC_DATA_DIR}/webxml/qtcore-index.webxml")
+
+    add_custom_command(OUTPUT "${DOC_DATA_DIR}/webxml/qtcore-index.webxml"
+                       # 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=${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...")
 endif()
 
 # conditional tag for sphinx build
@@ -171,22 +172,24 @@ endif()
 # create conf.py based on conf.py.in
 configure_file("conf.py.in" "rst/conf.py" @ONLY)
 
+add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/rst/PySide6/QtCore/index.rst"
+                   COMMAND Shiboken6::shiboken6 --generator-set=qtdoc ${docHeader}
+                           --include-paths="${QT_INCLUDE_DIR}${PATH_SEP}${pyside6_SOURCE_DIR}${PATH_SEP}${TS_ROOT}"
+                           --api-version=${SUPPORTED_QT_VERSION}
+                           --typesystem-paths="${QDOC_TYPESYSTEM_PATH}"
+                           --library-source-dir=${QT_SRC_DIR}
+                           --documentation-data-dir=${DOC_DATA_DIR}/webxml
+                           --output-directory=${CMAKE_CURRENT_BINARY_DIR}/rst
+                           --documentation-code-snippets-dir=${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets/doc/src/snippets${PATH_SEP}${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets/examples
+                           --documentation-extra-sections-dir=${CMAKE_CURRENT_BINARY_DIR}/rst/extras
+                           --additional-documentation=${CMAKE_CURRENT_BINARY_DIR}/rst/additionaldocs.lst
+                           ${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml
+                   WORKING_DIRECTORY ${${module}_SOURCE_DIR}
+                   COMMENT "Running generator to generate documentation...")
+
 add_custom_target("docrsts"
     COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/rst
-    COMMAND Shiboken6::shiboken6 --generator-set=qtdoc ${docHeader}
-            --include-paths="${QT_INCLUDE_DIR}${PATH_SEP}${pyside6_SOURCE_DIR}${PATH_SEP}${TS_ROOT}"
-            --api-version=${SUPPORTED_QT_VERSION}
-            --typesystem-paths="${QDOC_TYPESYSTEM_PATH}"
-            --library-source-dir=${QT_SRC_DIR}
-            --documentation-data-dir=${DOC_DATA_DIR}/webxml
-            --output-directory=${CMAKE_CURRENT_BINARY_DIR}/rst
-            --documentation-code-snippets-dir=${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets/doc/src/snippets${PATH_SEP}${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets/examples
-            --documentation-extra-sections-dir=${CMAKE_CURRENT_BINARY_DIR}/rst/extras
-            --additional-documentation=${CMAKE_CURRENT_BINARY_DIR}/rst/additionaldocs.lst
-            ${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml
-    WORKING_DIRECTORY ${${module}_SOURCE_DIR}
-    COMMENT "Running generator to generate documentation..."
-)
+    DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/rst/PySide6/QtCore/index.rst")
 
 add_custom_target("licensedocrsts"
     COMMAND ${PYTHON_EXECUTABLE}
diff --git a/sources/pyside6/doc/gettingstarted.rst b/sources/pyside6/doc/gettingstarted.rst
index 18c5dba21..bfdcc92b4 100644
--- a/sources/pyside6/doc/gettingstarted.rst
+++ b/sources/pyside6/doc/gettingstarted.rst
@@ -140,7 +140,7 @@ for the local Python related notes.
 The system required ``libxml2`` and ``libxslt``, also on the Python environment, ``sphinx`` and
 ``graphviz`` need to be installed before running the installation process::
 
-    pip install graphviz sphinx
+    pip install graphviz sphinx sphinx_tabs
 
 After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise,
 the process will fail. Installing ``graphviz`` system-wide is also an option.
@@ -155,10 +155,21 @@ directory, and run::
 
     ninja apidoc
 
-.. note:: The :command:`apidoc` make target builds offline documenation in QCH (Qt Creator Help)
+.. note:: The :command:`apidoc` make target builds offline documentation in QCH (Qt Creator Help)
    format by default. You can switch to building for the online use with the ``--doc-build-online``
    configure option.
 
+The target executes several steps:
+
+#. The ``qdoc`` tool is run over the Qt source code to produce documentation in WebXML format.
+#. ``shiboken6`` is run to extract the functions for which bindings exist from WebXML and convert it into RST.
+#. ``sphinx`` is run to produce the documentation in HTML format.
+
+Re-running the command will not execute step 1 unless the file
+``qdoc_output/webxml/qtcore-index.webxml`` is removed from the build tree.
+Similarly, step 2 will not be executed unless the file ``rst/PySide6/QtCore/index.rst``
+is removed.
+
 Finally, you will get a ``html`` directory containing all the generated documentation. The offline
 help files, ``PySide.qch`` and ``Shiboken.qch``, can be moved to any directory of your choice. You
 can find ``Shiboken.qch`` in the build directory, ``*_build\*_release\shiboken6\doc\html``.