Add command to build rst documentation only

Since the process to get the documentation built
is to build the whole project, that is too time consuming.
Additionally, using qdoc on the Qt API takes a lot of time.

This patch introduces the setup.py option called 'build_rst_docs'
which skip the general build, and only generates HTML documentation
based on all the .rst files we have for shiboken and pyside.

To use it:
    python setup.py build_rst_docs

The build will throw warnings related missing directories, and files,
which are generated on the 'qdoc' process, but since they are skipped
they are not present.

Some missing references warnings are skipped due to also come from
the qdoc-based step.

Task-number: PYSIDE-1106
Fixes: PYSIDE-1390
Change-Id: I4118fd3b64e217717df6cae093138f6951d37094
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@qt.io>

2 files changed, 87 insertions, 73 deletions

diff --git a/sources/pyside2/doc/CMakeLists.txt b/sources/pyside2/doc/CMakeLists.txt
index ffbb3c1eb..ab5d694e7 100644
--- a/sources/pyside2/doc/CMakeLists.txt
+++ b/sources/pyside2/doc/CMakeLists.txt
@@ -16,84 +16,90 @@ set(TS_ROOT "${ROOT}/PySide2")
 
 file(REMOVE ${CMAKE_CURRENT_LIST_DIR}/pyside.qdocconf ${CMAKE_CURRENT_LIST_DIR}/pyside.qdocconf.in)
 
-# For Qt modules that are part of the documentation build:
-#    - Configure the module docconf file
-#    - Write shiboken header consisting of pyside2_global.h and module includes
-#    - Build include path for qdoc for shiboken
-
-# The last element of the include list is the mkspec directory containing qplatformdefs.h
-list(GET Qt${QT_MAJOR_VERSION}Core_INCLUDE_DIRS -1 mkspecInclude)
-configure_file("pyside-config.qdocconf.in" "${CMAKE_CURRENT_LIST_DIR}/pyside-config.qdocconf" @ONLY)
-
-file(READ "${pyside2_BINARY_DIR}/pyside2_global.h" docHeaderContents)
-file(READ "typesystem_doc.xml.in" typeSystemDocXmlContents)
-
+set(SHIBOKEN_INTERSPHINX_FILE "${ROOT}/pyside2/shiboken2/objects.inv")
 set(HAS_WEBENGINE_WIDGETS 0)
-
-foreach(moduleIn ${all_module_shortnames})
-    string(TOLOWER "${moduleIn}" lowerModuleIn)
-    set(docConf "${CMAKE_CURRENT_LIST_DIR}/qtmodules/pyside-qt${lowerModuleIn}.qdocconf.in")
-    if(EXISTS "${docConf}")
-        string(REGEX REPLACE "(^.*)\.in" "\\1" OUTFILE ${docConf})
-        get_filename_component(BASENAME ${OUTFILE} NAME)
-        configure_file(${docConf} "${CMAKE_CURRENT_LIST_DIR}/qtmodules/${BASENAME}" @ONLY)
-        file(APPEND "pyside.qdocconf.in" "\@CMAKE_CURRENT_LIST_DIR\@/qtmodules/${BASENAME}\n")
-        # Handle docconf files in Qt that contain multiple modules
-        if ("${moduleIn}" STREQUAL "3DExtras")
-            set(modules 3DCore 3DRender 3DInput 3DLogic 3DAnimation "${moduleIn}")
-        elseif ("${moduleIn}" STREQUAL "QuickWidgets")
-            set(modules Qml Quick "${moduleIn}")
-        elseif ("${moduleIn}" STREQUAL "MultimediaWidgets")
-            set(modules Multimedia "${moduleIn}")
-        elseif ("${moduleIn}" STREQUAL "WebEngineWidgets")
-            set(modules WebEngine WebEngineCore "${moduleIn}")
-            set(HAS_WEBENGINE_WIDGETS 1)
-        else()
-            set(modules "${moduleIn}")
-        endif()
-        foreach(module ${modules})
-            string(TOLOWER "${module}" lowerModule)
-            # -- @TODO fix this for macOS frameworks.
-            file(APPEND "${CMAKE_CURRENT_LIST_DIR}/pyside-config.qdocconf"
-                 "    -I ${QT_INCLUDE_DIR}Qt${module} \\\n"
-                 "    -I ${QT_INCLUDE_DIR}Qt${module}/${Qt${QT_MAJOR_VERSION}Core_VERSION} \\\n"
-                 "    -I ${QT_INCLUDE_DIR}Qt${module}/${Qt${QT_MAJOR_VERSION}Core_VERSION}/Qt${module} \\\n")
-
-            if (${moduleIn} STREQUAL "X11Extras")
-                set(globalHeader "QX11Info")
+set(SKIP_SPHINX_WARNINGS 1)
+if (FULLDOCSBUILD)
+    set(SKIP_SPHINX_WARNINGS 0)
+    set(SHIBOKEN_INTERSPHINX_FILE "${CMAKE_BINARY_DIR}/doc/html/shiboken2/doc/html/objects.inv")
+    # For Qt modules that are part of the documentation build:
+    #    - Configure the module docconf file
+    #    - Write shiboken header consisting of pyside2_global.h and module includes
+    #    - Build include path for qdoc for shiboken
+
+    # The last element of the include list is the mkspec directory containing qplatformdefs.h
+    list(GET Qt${QT_MAJOR_VERSION}Core_INCLUDE_DIRS -1 mkspecInclude)
+    configure_file("pyside-config.qdocconf.in" "${CMAKE_CURRENT_LIST_DIR}/pyside-config.qdocconf" @ONLY)
+
+    file(READ "${pyside2_BINARY_DIR}/pyside2_global.h" docHeaderContents)
+    file(READ "typesystem_doc.xml.in" typeSystemDocXmlContents)
+
+
+    foreach(moduleIn ${all_module_shortnames})
+        string(TOLOWER "${moduleIn}" lowerModuleIn)
+        set(docConf "${CMAKE_CURRENT_LIST_DIR}/qtmodules/pyside-qt${lowerModuleIn}.qdocconf.in")
+        if(EXISTS "${docConf}")
+            string(REGEX REPLACE "(^.*)\.in" "\\1" OUTFILE ${docConf})
+            get_filename_component(BASENAME ${OUTFILE} NAME)
+            configure_file(${docConf} "${CMAKE_CURRENT_LIST_DIR}/qtmodules/${BASENAME}" @ONLY)
+            file(APPEND "pyside.qdocconf.in" "\@CMAKE_CURRENT_LIST_DIR\@/qtmodules/${BASENAME}\n")
+            # Handle docconf files in Qt that contain multiple modules
+            if ("${moduleIn}" STREQUAL "3DExtras")
+                set(modules 3DCore 3DRender 3DInput 3DLogic 3DAnimation "${moduleIn}")
+            elseif ("${moduleIn}" STREQUAL "QuickWidgets")
+                set(modules Qml Quick "${moduleIn}")
+            elseif ("${moduleIn}" STREQUAL "MultimediaWidgets")
+                set(modules Multimedia "${moduleIn}")
+            elseif ("${moduleIn}" STREQUAL "WebEngineWidgets")
+                set(modules WebEngine WebEngineCore "${moduleIn}")
+                set(HAS_WEBENGINE_WIDGETS 1)
             else()
-                set(globalHeader "Qt${module}")
+                set(modules "${moduleIn}")
             endif()
-            set(docHeaderContents "${docHeaderContents}\n#include <Qt${module}/${globalHeader}>")
-            set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n<load-typesystem name=\"Qt${module}/typesystem_${lowerModule}.xml\" generate=\"yes\"/>")
-        endforeach()
-    endif()
-endforeach()
+            foreach(module ${modules})
+                string(TOLOWER "${module}" lowerModule)
+                # -- @TODO fix this for macOS frameworks.
+                file(APPEND "${CMAKE_CURRENT_LIST_DIR}/pyside-config.qdocconf"
+                     "    -I ${QT_INCLUDE_DIR}Qt${module} \\\n"
+                     "    -I ${QT_INCLUDE_DIR}Qt${module}/${Qt${QT_MAJOR_VERSION}Core_VERSION} \\\n"
+                     "    -I ${QT_INCLUDE_DIR}Qt${module}/${Qt${QT_MAJOR_VERSION}Core_VERSION}/Qt${module} \\\n")
+
+                if (${moduleIn} STREQUAL "X11Extras")
+                    set(globalHeader "QX11Info")
+                else()
+                    set(globalHeader "Qt${module}")
+                endif()
+                set(docHeaderContents "${docHeaderContents}\n#include <Qt${module}/${globalHeader}>")
+                set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n<load-typesystem name=\"Qt${module}/typesystem_${lowerModule}.xml\" generate=\"yes\"/>")
+            endforeach()
+        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")
+    #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}")
+    set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n</typesystem>\n")
+    file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}")
 
-set(docHeader "${pyside2_BINARY_DIR}/qdoc.h")
-file(WRITE ${docHeader} "${docHeaderContents}")
+    set(docHeader "${pyside2_BINARY_DIR}/qdoc.h")
+    file(WRITE ${docHeader} "${docHeaderContents}")
+    configure_file("pyside.qdocconf.in" "pyside.qdocconf" @ONLY)
 
-configure_file("pyside.qdocconf.in" "pyside.qdocconf" @ONLY)
 
-set(QDOC_TYPESYSTEM_PATH "${pyside2_SOURCE_DIR}${PATH_SEP}${pyside2_BINARY_DIR}")
+    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=${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
+                    # 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")
+endif()
 
 # conditional tag for sphinx build
 #string(JOIN "_" SPHINX_TAG ${DOC_OUTPUT_FORMAT} "format")
@@ -168,9 +174,11 @@ add_custom_target("licensedocrsts"
     COMMENT "Creating 3rdparty license documentation..."
 )
 
-add_dependencies(apidoc docrsts licensedocrsts)
-add_dependencies(licensedocrsts docrsts)
-add_dependencies(docrsts qdoc)
+if (FULLDOCSBUILD)
+    add_dependencies(apidoc docrsts licensedocrsts)
+    add_dependencies(licensedocrsts docrsts)
+    add_dependencies(docrsts qdoc)
+endif()
 
 #install files
 add_custom_target(apidocinstall
diff --git a/sources/pyside2/doc/conf.py.in b/sources/pyside2/doc/conf.py.in
index e37abcb24..ae1bc6455 100644
--- a/sources/pyside2/doc/conf.py.in
+++ b/sources/pyside2/doc/conf.py.in
@@ -175,10 +175,16 @@ html_show_sourcelink = False
 
 # Link to the shiboken2 sphinx project to enable linking
 # between the two projects.
-intersphinx_mapping = {'shiboken2': ('shiboken2','@CMAKE_BINARY_DIR@/doc/html/shiboken2/doc/html/objects.inv')}
+intersphinx_mapping = {'shiboken2': ('shiboken2','@SHIBOKEN_INTERSPHINX_FILE@')}
 
 add_module_names = False
 
+# Skip some warnings when building the documentation with
+# 'build_rst_docs' due to the lack of qdoc generated files, in charge
+# of sphinx modules (autodoc) and references.
+if @SKIP_SPHINX_WARNINGS@:
+    suppress_warnings = ["autodoc", "autodoc.import_object", "ref.ref"]
+
 # -- Options for qthelp output ---------------------------------------------------
 qthelp_theme = 'pysidedocs_qthelp'