diff options
author | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2020-09-26 21:11:16 +0200 |
---|---|---|
committer | Cristian Maureira-Fredes <Cristian.Maureira-Fredes@qt.io> | 2020-09-29 20:34:54 +0200 |
commit | ff792fd2e6842b990aff61a4e953dab5efbd89ae (patch) | |
tree | 4e51f0d864fbefabe1bcb6c074e345b393dceaa2 | |
parent | 510bc5b2cf2196d31e950f16d5cfcf6ee1238f47 (diff) |
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>
-rw-r--r-- | build_scripts/main.py | 84 | ||||
-rw-r--r-- | sources/pyside2/doc/CMakeLists.txt | 152 | ||||
-rw-r--r-- | sources/pyside2/doc/conf.py.in | 8 | ||||
-rw-r--r-- | sources/shiboken2/doc/CMakeLists.txt | 3 |
4 files changed, 173 insertions, 74 deletions
diff --git a/build_scripts/main.py b/build_scripts/main.py index 99cc02185..73e667839 100644 --- a/build_scripts/main.py +++ b/build_scripts/main.py @@ -122,6 +122,7 @@ from distutils.spawn import find_executable from distutils.command.build import build as _build from distutils.command.build_ext import build_ext as _build_ext from distutils.util import get_platform +from distutils.cmd import Command from setuptools import Extension from setuptools.command.install import install as _install @@ -1066,6 +1067,9 @@ class PysideBuild(_build): log.info("Output format will be qthelp") cmake_cmd.append("-DDOC_OUTPUT_FORMAT=qthelp") + # Build the whole documentation (rst + API) by default + cmake_cmd.append("-DFULLDOCSBUILD=1") + if not OPTION["SKIP_CMAKE"]: log.info("Configuring module {} ({})...".format(extension, module_src_dir)) if run_process(cmake_cmd) != 0: @@ -1316,6 +1320,83 @@ class PysideBuild(_build): log.info("Patched rpath to '$ORIGIN/' (Linux) or " "updated rpath (OS/X) in {}.".format(srcpath)) +class PysideRstDocs(Command): + description = "Build .rst documentation only" + user_options = [] + def initialize_options(self): + log.info("-- This build process will not include the API documentation." + "API documentation requires a full build of pyside/shiboken.") + self.skip = False + if config.is_internal_shiboken_generator_build(): + self.skip = True + if not self.skip: + self.name = config.package_name().lower() + self.doc_dir = os.path.join(config.setup_script_dir, "sources") + self.doc_dir = os.path.join(self.doc_dir, self.name) + self.doc_dir = os.path.join(self.doc_dir, "doc") + try: + # Check if sphinx is installed to proceed. + import sphinx + if self.name == "shiboken2": + log.info("-- Generating Shiboken documentation") + log.info("-- Documentation directory: 'html/pyside2/shiboken2/'") + elif self.name == "pyside2": + log.info("-- Generating PySide documentation") + log.info("-- Documentation directory: 'html/pyside2/'") + except ImportError: + raise DistutilsSetupError("Sphinx not found - aborting") + self.html_dir = "html" + + # creating directories html/pyside2/shiboken2 + try: + if not os.path.isdir(self.html_dir): + os.mkdir(self.html_dir) + if self.name == "shiboken2": + out_pyside = os.path.join(self.html_dir, "pyside2") + if not os.path.isdir(out_pyside): + os.mkdir(out_pyside) + out_shiboken = os.path.join(out_pyside, "shiboken2") + if not os.path.isdir(out_shiboken): + os.mkdir(out_shiboken) + self.out_dir = out_shiboken + # We know that on the shiboken step, we already created the + # 'pyside2' directory + elif self.name == "pyside2": + self.out_dir = os.path.join(self.html_dir, "pyside2") + except: + raise DistutilsSetupError("Error while creating directories for {}".format(self.doc_dir)) + + def run(self): + if not self.skip: + cmake_cmd = [OPTION["CMAKE"]] + cmake_cmd += [ + "-S", self.doc_dir, + "-B", self.out_dir, + "-DDOC_OUTPUT_FORMAT=html", + "-DFULLDOCSBUILD=0", + ] + if run_process(cmake_cmd) != 0: + raise DistutilsSetupError("Error running CMake for {}".format(self.doc_dir)) + + if self.name == "pyside2": + self.sphinx_src = os.path.join(self.out_dir, "rst") + elif self.name == "shiboken2": + self.sphinx_src = self.out_dir + + sphinx_cmd = ["sphinx-build", + "-b", "html", + "-c", self.sphinx_src, + self.doc_dir, + self.out_dir + ] + if run_process(sphinx_cmd) != 0: + raise DistutilsSetupError("Error running CMake for {}".format(self.doc_dir)) + # Last message + if not self.skip and self.name == "pyside2": + log.info("-- The documentation was built. Check html/pyside2/index.html") + + def finalize_options(self): + pass cmd_class_dict = { 'build': PysideBuild, @@ -1324,7 +1405,8 @@ cmd_class_dict = { 'bdist_egg': PysideBdistEgg, 'develop': PysideDevelop, 'install': PysideInstall, - 'install_lib': PysideInstallLib + 'install_lib': PysideInstallLib, + 'build_rst_docs': PysideRstDocs, } if wheel_module_exists: params = {} 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' diff --git a/sources/shiboken2/doc/CMakeLists.txt b/sources/shiboken2/doc/CMakeLists.txt index 9fee96298..ae4858f95 100644 --- a/sources/shiboken2/doc/CMakeLists.txt +++ b/sources/shiboken2/doc/CMakeLists.txt @@ -1,5 +1,8 @@ cmake_minimum_required(VERSION 3.1) +if(FULLDOCSBUILD EQUAL 0) + project(shiboken2_doc) +endif() find_program(SPHINX sphinx-build DOC "Path to sphinx-build binary.") if (SPHINX) |