diff options
Diffstat (limited to 'sources/pyside6/doc/CMakeLists.txt')
| -rw-r--r-- | sources/pyside6/doc/CMakeLists.txt | 173 |
1 files changed, 93 insertions, 80 deletions
diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt index 9d4fcf144..83583756f 100644 --- a/sources/pyside6/doc/CMakeLists.txt +++ b/sources/pyside6/doc/CMakeLists.txt @@ -1,5 +1,8 @@ -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") @@ -29,7 +32,7 @@ if(NOT CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME) return() endif() else() - # We are building the docs as a standalone project, likely via setup.py build_rst_docs + # 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.") @@ -48,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") @@ -55,10 +64,9 @@ 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) @@ -70,13 +78,15 @@ endif() if(PYSIDE_IS_CROSS_BUILD) set(python_executable "${QFP_PYTHON_HOST_PATH}") else() - set(python_executable "${PYTHON_EXECUTABLE}") + 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 "${CMAKE_CURRENT_SOURCE_DIR}/../../../tools/snippets_translate/main.py") - set(SNIPPETS_TARGET ${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets) + 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 @@ -89,12 +99,12 @@ if (FULLDOCSBUILD) endif() # Generate example gallery -set(EXAMPLE_TOOL_TARGET "${CMAKE_CURRENT_BINARY_DIR}/rst/examples") -set(EXAMPLE_TOOL_OPTIONS --target "${EXAMPLE_TOOL_TARGET}") +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) list(APPEND EXAMPLE_TOOL_OPTIONS "-q") endif() -set(EXAMPLE_TOOL_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../../../tools/example_gallery/main.py") +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}" @@ -115,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}") @@ -129,46 +152,16 @@ 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 WebEngineCore WebEngineWidgets WebEngineQuick "${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") - - set(globalHeader "Qt${module}") - 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() - set(typeSystemDocXmlContents "${typeSystemDocXmlContents}\n</typesystem>\n") - file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/typesystem_doc.xml" "${typeSystemDocXmlContents}") + # 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(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}") @@ -183,18 +176,25 @@ if (FULLDOCSBUILD) 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_binary}" 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() +# 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..." ) @@ -207,6 +207,7 @@ 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() if(qhelpgenerator_binary) @@ -215,9 +216,10 @@ else() 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} -f ${QHP_FILE} -v pyside6 + 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() @@ -226,42 +228,53 @@ else() endif() # create conf.py based on conf.py.in -configure_file("conf.py.in" "rst/conf.py" @ONLY) - -set(CODE_SNIPPET_ROOT "${CMAKE_CURRENT_BINARY_DIR}/rst/codesnippets") - -add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/rst/PySide6/QtCore/index.rst" - COMMAND Shiboken6::shiboken6 --generator-set=qtdoc ${docHeader} - --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}/rst - --documentation-code-snippets-dir=${CODE_SNIPPET_ROOT} - --snippets-path-rewrite=${QT_ROOT_PATH}:${CODE_SNIPPET_ROOT} - --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}/rst/extras" - COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/rst +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}/rst/extras") + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/${DOC_BASE_DIR}/extras") add_custom_target("docrsts" - 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} ${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..." ) |