From ff792fd2e6842b990aff61a4e953dab5efbd89ae Mon Sep 17 00:00:00 2001 From: Cristian Maureira-Fredes Date: Sat, 26 Sep 2020 21:11:16 +0200 Subject: 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 --- sources/pyside2/doc/CMakeLists.txt | 152 +++++++++++++++++++------------------ sources/pyside2/doc/conf.py.in | 8 +- 2 files changed, 87 insertions(+), 73 deletions(-) (limited to 'sources/pyside2/doc') 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 ") - set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n") - 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 ") + set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n") + 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\n") -file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}") + set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n\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' -- cgit v1.2.3