diff options
author | Friedemann Kleint <Friedemann.Kleint@qt.io> | 2021-02-25 17:34:52 +0100 |
---|---|---|
committer | Qt Cherry-pick Bot <cherrypick_bot@qt-project.org> | 2021-02-26 09:12:34 +0000 |
commit | 93ae3d9b38649e9d683a658a6a19b7623083f5a0 (patch) | |
tree | 26597ec9bfcac9802d6c4c5af2cdd2417b03adb2 | |
parent | a84a9f1c001b76989f104fefc877624ee683dc0f (diff) |
Documentation build: Avoid re-running qdoc/shiboken every time
The qdoc and shiboken steps take quite a long time when
rebuilding the documentation.
Similar to the generator dependency on
mjb_rejected_classes.log (see CMake macro
create_generator_target_library_name /
sources/cmake_helpers/helpers.cmake:262)), turn the
qdoc/shiboken targets into custom commands producing specific
files (qtcore-index.webxml, QtCore/index.rst).
This prevents the commands from being re-run as long
as the files exist and are not outdated.
Adapt the documentation.
Change-Id: I00033e6f1034a5fdc534a0f2fee018268e2e482a
Reviewed-by: Cristian Maureira-Fredes <cristian.maureira-fredes@qt.io>
(cherry picked from commit 1251fb08619e030665651ea965c1ee6c283b9913)
Reviewed-by: Qt Cherry-pick Bot <cherrypick_bot@qt-project.org>
-rw-r--r-- | sources/pyside6/doc/CMakeLists.txt | 49 | ||||
-rw-r--r-- | sources/pyside6/doc/gettingstarted.rst | 15 |
2 files changed, 39 insertions, 25 deletions
diff --git a/sources/pyside6/doc/CMakeLists.txt b/sources/pyside6/doc/CMakeLists.txt index b89d5c5e4..634ebb252 100644 --- a/sources/pyside6/doc/CMakeLists.txt +++ b/sources/pyside6/doc/CMakeLists.txt @@ -112,15 +112,16 @@ if (FULLDOCSBUILD) set(QDOC_TYPESYSTEM_PATH "${pyside6_SOURCE_DIR}${PATH_SEP}${pyside6_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 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} + COMMENT "Running qdoc against Qt source code...") endif() # conditional tag for sphinx build @@ -171,22 +172,24 @@ 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 + WORKING_DIRECTORY ${${module}_SOURCE_DIR} + COMMENT "Running generator to generate documentation...") + add_custom_target("docrsts" COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_BINARY_DIR}/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 - WORKING_DIRECTORY ${${module}_SOURCE_DIR} - COMMENT "Running generator to generate documentation..." -) + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/rst/PySide6/QtCore/index.rst") add_custom_target("licensedocrsts" COMMAND ${PYTHON_EXECUTABLE} diff --git a/sources/pyside6/doc/gettingstarted.rst b/sources/pyside6/doc/gettingstarted.rst index 18c5dba21..bfdcc92b4 100644 --- a/sources/pyside6/doc/gettingstarted.rst +++ b/sources/pyside6/doc/gettingstarted.rst @@ -140,7 +140,7 @@ for the local Python related notes. The system required ``libxml2`` and ``libxslt``, also on the Python environment, ``sphinx`` and ``graphviz`` need to be installed before running the installation process:: - pip install graphviz sphinx + pip install graphviz sphinx sphinx_tabs After installing ``graphviz``, the ``dot`` command needs to be in PATH, otherwise, the process will fail. Installing ``graphviz`` system-wide is also an option. @@ -155,10 +155,21 @@ directory, and run:: ninja apidoc -.. note:: The :command:`apidoc` make target builds offline documenation in QCH (Qt Creator Help) +.. note:: The :command:`apidoc` make target builds offline documentation in QCH (Qt Creator Help) format by default. You can switch to building for the online use with the ``--doc-build-online`` configure option. +The target executes several steps: + +#. The ``qdoc`` tool is run over the Qt source code to produce documentation in WebXML format. +#. ``shiboken6`` is run to extract the functions for which bindings exist from WebXML and convert it into RST. +#. ``sphinx`` is run to produce the documentation in HTML format. + +Re-running the command will not execute step 1 unless the file +``qdoc_output/webxml/qtcore-index.webxml`` is removed from the build tree. +Similarly, step 2 will not be executed unless the file ``rst/PySide6/QtCore/index.rst`` +is removed. + Finally, you will get a ``html`` directory containing all the generated documentation. The offline help files, ``PySide.qch`` and ``Shiboken.qch``, can be moved to any directory of your choice. You can find ``Shiboken.qch`` in the build directory, ``*_build\*_release\shiboken6\doc\html``. |