diff options
Diffstat (limited to 'sources/pyside6/doc/CMakeLists.txt')
| -rw-r--r-- | sources/pyside6/doc/CMakeLists.txt | 297 |
1 files changed, 189 insertions, 108 deletions
diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt index 634ebb252..83583756f 100644 --- a/sources/pyside6/doc/CMakeLists.txt +++ b/sources/pyside6/doc/CMakeLists.txt @@ -1,7 +1,48 @@ -cmake_minimum_required(VERSION 3.16) -cmake_policy(VERSION 3.16) +# Copyright (C) 2023 The Qt Company Ltd. +# SPDX-License-Identifier: BSD-3-Clause + +cmake_minimum_required(VERSION 3.18) +cmake_policy(VERSION 3.18) project(doc) +list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/../../shiboken6/cmake") +include(FindDocTools) + +# When the doc project is built as part of the pyside project, we show informational message +# and return early if requirements are not met. +if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME) + if(QT_SRC_DIR AND SPHINX_BUILD AND DOT_EXEC AND BUILD_DOCS) + # All requirements met, proceed. + else() + set(reasons "") + if(NOT QT_SRC_DIR) + list(APPEND reasons " QT_SRC_DIR variable not set\n") + endif() + if(NOT SPHINX_BUILD) + list(APPEND reasons " sphinx-build command not found\n") + endif() + if(NOT DOT_EXEC) + list(APPEND reasons " graphviz not found\n") + endif() + if(NOT BUILD_DOCS) + list(APPEND reasons " BUILD_DOCS was set to FALSE (default)\n") + endif() + message(STATUS "apidoc generation targets disabled due to the following reasons:\n" + ${reasons}) + return() + endif() +else() + # We are building the docs as a standalone project, likely via setup.py build_base_docs + # command. Perform stricter sanity checks. + if(NOT SPHINX_BUILD) + message(FATAL_ERROR "sphinx-build command not found. Please set the SPHINX_BUILD variable.") + endif() +endif() + +# Generate html by default. +if(NOT DOC_OUTPUT_FORMAT) + set(DOC_OUTPUT_FORMAT "html") +endif() if (WIN32) set(PATH_SEP "\;") @@ -10,6 +51,12 @@ else() endif() set(DOC_DATA_DIR "${CMAKE_CURRENT_BINARY_DIR}/qdoc-output") +# Directory for sphinx-generated files to build the HTML website. If changed, +# update "build_scripts/main.py" in "PysideBaseDocs" class at line: +# self.sphinx_src = self.out_dir / "base". +set(DOC_BASE_DIR "base") + +set(ENV_INHERITANCE_FILE "${CMAKE_CURRENT_BINARY_DIR}/inheritance.json") get_filename_component(ROOT ${CMAKE_CURRENT_BINARY_DIR} DIRECTORY) set(TS_ROOT "${ROOT}/PySide6") @@ -17,20 +64,53 @@ set(TS_ROOT "${ROOT}/PySide6") file(REMOVE ${CMAKE_CURRENT_LIST_DIR}/pyside.qdocconf ${CMAKE_CURRENT_LIST_DIR}/pyside.qdocconf.in) # We need to find the interpreter when running this only -# for a rst_build_docs case, and not a full doc build +# for the 'build_base_docs' case, and not a full doc build if (NOT FULLDOCSBUILD) find_package(Python COMPONENTS Interpreter) - set(PYTHON_EXECUTABLE ${Python_EXECUTABLE}) +endif() + +if (QT_SRC_DIR) + file(REAL_PATH ${QT_SRC_DIR}/.. QT_ROOT_PATH) +else() + set(QT_ROOT_PATH "") +endif() + +if(PYSIDE_IS_CROSS_BUILD) + set(python_executable "${QFP_PYTHON_HOST_PATH}") +else() + set(python_executable "${Python_EXECUTABLE}") +endif() + +set(TOOLS_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../tools") + +if (FULLDOCSBUILD) + # Fetch and transform the snippets from Qt + set(SNIPPETS_TOOL "${TOOLS_DIR}/snippets_translate/main.py") + set(SNIPPETS_TARGET ${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/codesnippets) + + # Note QT_SRC_DIR points to 'qtbase', + # so we use the general SRC directory to copy all the other snippets + add_custom_target("snippets_translate" DEPENDS "${SNIPPETS_TARGET}") + add_custom_command(OUTPUT "${SNIPPETS_TARGET}" + COMMAND ${python_executable} ${SNIPPETS_TOOL} + --qt ${QT_ROOT_PATH} --target ${SNIPPETS_TARGET} -w + WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} + COMMENT "Fetching and converting snippets...") endif() # Generate example gallery -message(STATUS "Generating example gallery") +set(EXAMPLE_TOOL_TARGET "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/examples") +set(EXAMPLE_TOOL_OPTIONS --target "${EXAMPLE_TOOL_TARGET}" --qt-src-dir "${QT_SRC_DIR}") if (QUIET_BUILD) - set (EXAMPLE_TOOL_OPTIONS "-q") + list(APPEND EXAMPLE_TOOL_OPTIONS "-q") endif() -set(EXAMPLE_TOOL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../tools/example_gallery/main.py") -execute_process(COMMAND ${PYTHON_EXECUTABLE} ${EXAMPLE_TOOL_DIR} ${EXAMPLE_TOOL_OPTIONS} - WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}) +set(EXAMPLE_TOOL_DIR "${TOOLS_DIR}/example_gallery/main.py") + +add_custom_target("example_gallery" DEPENDS "${EXAMPLE_TOOL_TARGET}") +add_custom_command(OUTPUT "${EXAMPLE_TOOL_TARGET}" + COMMAND ${python_executable} ${EXAMPLE_TOOL_DIR} ${EXAMPLE_TOOL_OPTIONS} + WORKING_DIRECTORY ${CMAKE_CURRENT_LIST_DIR} + COMMENT "Generating example gallery...") set(SHIBOKEN_INTERSPHINX_FILE "${ROOT}/pyside6/shiboken6/objects.inv") set(HAS_WEBENGINE_WIDGETS 0) @@ -45,13 +125,26 @@ if (FULLDOCSBUILD) # 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) + set(config_docconf "${CMAKE_CURRENT_LIST_DIR}/pyside-config.qdocconf") + configure_file("pyside-config.qdocconf.in" "${config_docconf}" @ONLY) + set(global_header "${pyside6_BINARY_DIR}/qdoc.h") file(READ "${pyside6_BINARY_DIR}/pyside6_global.h" docHeaderContents) + file(WRITE ${global_header} "${docHeaderContents}") + + set(global_typesystem "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml") file(READ "typesystem_doc.xml.in" typeSystemDocXmlContents) + file(WRITE ${global_typesystem} "${typeSystemDocXmlContents}") + execute_process( + COMMAND ${Python_EXECUTABLE} "${TOOLS_DIR}/doc_modules.py" + -t "${global_typesystem}" -g "${global_header}" -d "${config_docconf}" + "${QT_INCLUDE_DIR}" "${SUPPORTED_QT_VERSION}" + OUTPUT_VARIABLE ALL_DOC_MODULES + OUTPUT_STRIP_TRAILING_WHITESPACE) + separate_arguments (ALL_DOC_MODULES UNIX_COMMAND "${ALL_DOC_MODULES}") - foreach(moduleIn ${all_module_shortnames}) + foreach(moduleIn ${ALL_DOC_MODULES}) string(TOLOWER "${moduleIn}" lowerModuleIn) set(docConf "${CMAKE_CURRENT_LIST_DIR}/qtmodules/pyside-qt${lowerModuleIn}.qdocconf.in") if(EXISTS "${docConf}") @@ -59,94 +152,49 @@ if (FULLDOCSBUILD) 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 "OpenGL") - set(modules "${moduleIn}" OpenGLWidgets) - elseif ("${moduleIn}" STREQUAL "QuickWidgets") - set(modules Qml Quick "${moduleIn}") - elseif ("${moduleIn}" STREQUAL "MultimediaWidgets") - set(modules Multimedia "${moduleIn}") - elseif ("${moduleIn}" STREQUAL "Scxml") - set(modules StateMachine "${moduleIn}") - elseif ("${moduleIn}" STREQUAL "Svg") - set(modules "${moduleIn}" SvgWidgets) - 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") - 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") + # There is no binding for the qtdoc repository, but it has some relevant documents. + set(qtdoc_doc_conf "qtmodules/pyside-qtdoc.qdocconf") + configure_file("${qtdoc_doc_conf}.in" "${CMAKE_CURRENT_LIST_DIR}/${qtdoc_doc_conf}" @ONLY) + file(APPEND "pyside.qdocconf.in" "\@CMAKE_CURRENT_LIST_DIR\@/${qtdoc_doc_conf}\n") - set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n</typesystem>\n") - file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}") - - set(docHeader "${pyside6_BINARY_DIR}/qdoc.h") - file(WRITE ${docHeader} "${docHeaderContents}") configure_file("pyside.qdocconf.in" "pyside.qdocconf" @ONLY) + configure_file("qdoc_spawner.py.in" "qdoc_spawner.py" @ONLY) set(QDOC_TYPESYSTEM_PATH "${pyside6_SOURCE_DIR}${PATH_SEP}${pyside6_BINARY_DIR}") + if(NOT qdoc_binary) + message(FATAL_ERROR + "No qdoc binary was found which full documentation generation requires. " + "Please either add qdoc to PATH or specify the QDOC_EXECUTABLE variable." + ) + endif() + 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} + Use dummy Qt version information, QDoc needs it but has no effect on WebXML output + COMMAND ${CMAKE_COMMAND} -E env ${python_executable} qdoc_spawner.py + --qt=${QT_VERSION_MAJOR}.${QT_VERSION_MINOR}.${QT_VERSION_PATCH} + --doc-data-dir=${DOC_DATA_DIR} + --qdoc-binary=${qdoc_binary} + --build-dir=${CMAKE_CURRENT_LIST_DIR}/src + --qt-install-docs=${QT_SRC_DIR}/doc + --parallel="auto" + --verbose COMMENT "Running qdoc against Qt source code...") endif() -# conditional tag for sphinx build -#string(JOIN "_" SPHINX_TAG ${DOC_OUTPUT_FORMAT} "format") -# Python script to replace the virtualFolder string in the QHP -set(py_cmd " -import fileinput -import re -try: -\tfor line in fileinput.input('html/PySide.qhp',inplace=True,backup='.bak'): -\t\tline_copy=line.strip() -\t\tif not line_copy: # check for empty line -\t\t\tcontinue -\t\tmatch=re.match('(^.*virtualFolder.)doc(.*$)',line) -\t\tif match: -\t\t\trepl=''.join([match.group(1),'pyside6',match.group(2)]) -\t\t\tprint(line.replace(match.group(0),repl),end='') -\t\telse: -\t\t\tprint(line) -except: -\tpass\n") -file(GENERATE OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/py_script.py CONTENT ${py_cmd}) - +# Avoid using 'auto' for '-j' option as it could lead to +# crash on some systems due to out-of-memory situation. Instead +# use a no. less than 8. add_custom_target(apidoc - COMMAND ${SHIBOKEN_PYTHON_INTERPRETER} ${SPHINX_BUILD} -b ${DOC_OUTPUT_FORMAT} ${CMAKE_CURRENT_BINARY_DIR}/rst html + COMMAND ${CMAKE_COMMAND} -E env INHERITANCE_FILE=${ENV_INHERITANCE_FILE} + ${SHIBOKEN_PYTHON_INTERPRETER} ${SPHINX_BUILD} -b ${DOC_OUTPUT_FORMAT} + -j 6 ${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR} html COMMENT "Generating PySide htmls..." ) @@ -159,50 +207,83 @@ if(DOC_OUTPUT_FORMAT STREQUAL "html") ${CMAKE_CURRENT_BINARY_DIR}/../../shiboken6/doc/html ${CMAKE_CURRENT_BINARY_DIR}/html/shiboken6 COMMENT "Copying Shiboken docs..." + DEPENDS "${DOC_DATA_DIR}/webxml/qtcore-index.webxml" VERBATIM) else() - file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/PySide.qhp QHP_FILE) - add_custom_command(TARGET apidoc POST_BUILD - COMMAND ${PYTHON_EXECUTABLE} py_script.py - COMMAND qhelpgenerator ${QHP_FILE} - COMMENT "Generating QCH from a QHP file..." - VERBATIM) + if(qhelpgenerator_binary) + message(STATUS "qhelpgenerator - found") + # Python script that will be called to update the QHP + set(PATCH_QHP_SCRIPT "${CMAKE_CURRENT_LIST_DIR}/../../shiboken6/doc/scripts/patch_qhp.py") + file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/html/PySide.qhp QHP_FILE) + add_custom_command(TARGET apidoc POST_BUILD + COMMAND ${python_executable} ${PATCH_QHP_SCRIPT} -p -v pyside6 ${QHP_FILE} + COMMAND "${qhelpgenerator_binary}" ${QHP_FILE} + COMMENT "Generating QCH from a QHP file..." + DEPENDS "${DOC_DATA_DIR}/webxml/qtcore-index.webxml" + VERBATIM + ) + else() + message(WARNING "qhelpgenerator - not found! qch generation disabled") + endif() 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 +configure_file("conf.py.in" "${DOC_BASE_DIR}/conf.py" @ONLY) + +set(CODE_SNIPPET_ROOT "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/codesnippets") + +if (FULLDOCSBUILD) +shiboken_get_tool_shell_wrapper(shiboken tool_wrapper) + +add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/PySide6/QtCore/index.rst" + COMMAND + ${tool_wrapper} + $<TARGET_FILE:Shiboken6::shiboken6> + --generator-set=qtdoc + ${global_header} + --enable-pyside-extensions + --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}/${DOC_BASE_DIR} + --documentation-code-snippets-dir=${CODE_SNIPPET_ROOT} + --snippets-path-rewrite=${QT_ROOT_PATH}:${CODE_SNIPPET_ROOT} + --documentation-extra-sections-dir=${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/extras + --additional-documentation=${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/additionaldocs.lst + --inheritance-file=${ENV_INHERITANCE_FILE} + ${global_typesystem} WORKING_DIRECTORY ${${module}_SOURCE_DIR} COMMENT "Running generator to generate documentation...") +endif() + +add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/extras" + COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR} + COMMENT "Copying docs...") + +add_custom_target("doc_copy" + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/extras") add_custom_target("docrsts" - COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/rst - DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/rst/PySide6/QtCore/index.rst") + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/PySide6/QtCore/index.rst") +set(LIBEXEC_PATH "${QT6_INSTALL_PREFIX}/${QT6_INSTALL_LIBEXECS}") add_custom_target("licensedocrsts" - COMMAND ${PYTHON_EXECUTABLE} + COMMAND ${python_executable} ${CMAKE_CURRENT_LIST_DIR}/qtattributionsscannertorst.py + -l "${LIBEXEC_PATH}" ${CMAKE_CURRENT_LIST_DIR}/../../.. - ${CMAKE_CURRENT_BINARY_DIR}/rst/licenses.rst + ${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/licenses.rst COMMENT "Creating 3rdparty license documentation..." ) +add_dependencies(docrsts example_gallery) + if (FULLDOCSBUILD) add_dependencies(apidoc docrsts licensedocrsts) add_dependencies(licensedocrsts docrsts) - add_dependencies(docrsts qdoc) + add_dependencies(docrsts doc_copy qdoc snippets_translate) endif() #install files |