diff --git a/.gitlab/ci/configure_sphinx.cmake b/.gitlab/ci/configure_sphinx.cmake index 9f3f0bea7c..6798a098b5 100644 --- a/.gitlab/ci/configure_sphinx.cmake +++ b/.gitlab/ci/configure_sphinx.cmake @@ -1,6 +1,7 @@ set(SPHINX_INFO ON CACHE BOOL "") set(SPHINX_MAN ON CACHE BOOL "") set(SPHINX_HTML ON CACHE BOOL "") +set(SPHINX_HTML_COPYBUTTON ON CACHE BOOL "") set(SPHINX_SINGLEHTML ON CACHE BOOL "") set(SPHINX_QTHELP ON CACHE BOOL "") set(SPHINX_TEXT ON CACHE BOOL "") diff --git a/.gitlab/ci/docker/fedora44/deps_packages.lst b/.gitlab/ci/docker/fedora44/deps_packages.lst index b763bb7214..21f85b1701 100644 --- a/.gitlab/ci/docker/fedora44/deps_packages.lst +++ b/.gitlab/ci/docker/fedora44/deps_packages.lst @@ -35,6 +35,7 @@ zlib-devel # Install documentation tools. python3-sphinx python3-sphinxcontrib-qthelp +python3-sphinx-copybutton qt5-qttools-devel qt6-qttools-devel texinfo diff --git a/.gitlab/os-linux.yml b/.gitlab/os-linux.yml index 4c675f0743..2d66350260 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -82,7 +82,7 @@ ### Fedora .fedora44: - image: "kitware/cmake:ci-fedora44-x86_64-2026-04-30" + image: "kitware/cmake:ci-fedora44-x86_64-2026-08-20" variables: GIT_CLONE_PATH: "$CI_BUILDS_DIR/cmake ci/long file name for testing purposes" @@ -957,6 +957,7 @@ - cd build/ - cmake ../Utilities/Sphinx -GNinja -DSPHINX_HTML=ON + -DSPHINX_HTML_COPYBUTTON=ON -DSPHINX_QTHELP=$CMAKE_CI_SPHINX_QTHELP -DCMake_SPHINX_CMAKE_ORG=ON -DCMake_SPHINX_CMAKE_ORG_OUTDATED=$CMAKE_CI_SPHINX_OUTDATED diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index d757263e22..9b87f6c22a 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -116,7 +116,7 @@ The command has a few modes by which it searches for packages: A call to ``find_package()`` can be redirected internally to a package provided by the :module:`FetchContent` module. To the caller, the behavior will appear similar to Config mode, except that the search logic is - by-passed and the component information is not used. See + bypassed and the component information is not used. See :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable` for further details. diff --git a/Help/dev/documentation.rst b/Help/dev/documentation.rst index 500cf054f2..f7b14883ea 100644 --- a/Help/dev/documentation.rst +++ b/Help/dev/documentation.rst @@ -24,6 +24,24 @@ repository to ``build/html`` and ``build/man`` directories: $ cmake -S Utilities/Sphinx -B build -DSPHINX_HTML=ON -DSPHINX_MAN=ON $ cmake --build build +Depending on how Sphinx is installed on the system, optionally configure with +``-DSPHINX_EXECUTABLE=/path/to/sphinx-build``. + +Sphinx Extensions +----------------- + +When building the HTML help, CMake uses the following third-party +`extensions`_: + +* `sphinx-copybutton`_: Adds an interactive copy button to the corner of + ``code-block`` directives. To generate the documentation locally with this + extension, configure CMake as above with ``-DSPHINX_HTML_COPYBUTTON=ON``. + Ensure the extension is installed in the same environment (or on the system) + as the ``SPHINX_EXECUTABLE``. + +.. _`extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html +.. _`sphinx-copybutton`: https://sphinx-copybutton.readthedocs.io/en/latest/ + Markup Constructs ----------------- diff --git a/README.rst b/README.rst index a10da9c526..b76595e60a 100644 --- a/README.rst +++ b/README.rst @@ -57,12 +57,14 @@ generator and options. Then build it and install it. To build the documentation, install `Sphinx`_ and configure CMake with ``-DSPHINX_HTML=ON`` and/or ``-DSPHINX_MAN=ON`` to enable the "html" or "man" builder. Add ``-DSPHINX_EXECUTABLE=/path/to/sphinx-build`` if the -tool is not found automatically. +tool is not found automatically. See the `CMake Documentation Guide`_ for +details. To run the test suite, run ``ctest`` in the CMake build directory after building. See the `CMake Testing Guide`_ for details. .. _`Sphinx`: https://sphinx-doc.org +.. _`CMake Documentation Guide`: Help/dev/documentation.rst .. _`CMake Testing Guide`: Help/dev/testing.rst Building CMake from Scratch diff --git a/Source/cmFindPackageCommand.cxx b/Source/cmFindPackageCommand.cxx index 054afe14d2..25934a2f93 100644 --- a/Source/cmFindPackageCommand.cxx +++ b/Source/cmFindPackageCommand.cxx @@ -1246,7 +1246,7 @@ bool cmFindPackageCommand::FindPackage( // When this property is set, the FetchContent module has already been // included at least once, so we know the FetchContent_MakeAvailable() // command will be defined. Any future find_package() calls after this - // one for this package will by-pass this once-only delegation. + // one for this package will bypass this once-only delegation. // The following call will typically create a -config.cmake file // in the redirectsDir, which we still want to process like any other // config file to ensure we follow normal find_package() processing. diff --git a/Tests/CPackComponentsForAll/CMakeLists.txt b/Tests/CPackComponentsForAll/CMakeLists.txt index 253a03554b..45d2f03b9b 100644 --- a/Tests/CPackComponentsForAll/CMakeLists.txt +++ b/Tests/CPackComponentsForAll/CMakeLists.txt @@ -149,7 +149,7 @@ set(CPACK_COMPONENT_GROUP_DEVELOPMENT_DESCRIPTION # depend on the libraries component. set(CPACK_COMPONENT_HEADERS_DEPENDS libraries) -# Create two installation types with pre-selected components. +# Create two installation types with preselected components. # The "Developer" installation has just the library and headers, # while the "Full" installation has everything. set(CPACK_ALL_INSTALL_TYPES Full Developer) diff --git a/Tests/FindImageMagick/Test/main_magick++.cxx b/Tests/FindImageMagick/Test/main_magick++.cxx index 95aba8bf7e..71985fd4d3 100644 --- a/Tests/FindImageMagick/Test/main_magick++.cxx +++ b/Tests/FindImageMagick/Test/main_magick++.cxx @@ -11,6 +11,14 @@ int main() std::string found_version = std::string(MagickLibVersionText) + MagickLibAddendum; + // Pre-release builds append an annotation such as " (Beta)" to + // MagickLibAddendum which FindImageMagick's ImageMagick_VERSION does not + // include. + std::string::size_type annotation = found_version.find(" ("); + if (annotation != std::string::npos) { + found_version.erase(annotation); + } + std::cout << "Found ImageMagick version " << found_version << ", expected version " << CMAKE_EXPECTED_IMAGEMAGICK_VERSION << "\n"; diff --git a/Utilities/Sphinx/CMakeLists.txt b/Utilities/Sphinx/CMakeLists.txt index ee6becdbac..f80db687af 100644 --- a/Utilities/Sphinx/CMakeLists.txt +++ b/Utilities/Sphinx/CMakeLists.txt @@ -22,6 +22,7 @@ project(CMakeHelp NONE) option(SPHINX_INFO "Build Info manual with Sphinx" OFF) option(SPHINX_MAN "Build man pages with Sphinx" OFF) option(SPHINX_HTML "Build html help with Sphinx" OFF) +option(SPHINX_HTML_COPYBUTTON "Build html help with the sphinx-copybutton extension" OFF) option(SPHINX_SINGLEHTML "Build html single page help with Sphinx" OFF) option(SPHINX_LINKCHECK "Check external links mentioned in documentation" OFF) option(SPHINX_QTHELP "Build Qt help with Sphinx" OFF) @@ -70,6 +71,11 @@ else() set(conf_cmakeorg "False") endif() +set(conf_copybutton_ext) +if (SPHINX_HTML_COPYBUTTON) + set(conf_copybutton_ext "\'sphinx_copybutton\',") +endif() + set(conf_docs "${CMake_SOURCE_DIR}/Help") set(conf_path "${CMAKE_CURRENT_SOURCE_DIR}") set(conf_version "${CMake_VERSION_MAJOR}.${CMake_VERSION_MINOR}.${CMake_VERSION_PATCH}") diff --git a/Utilities/Sphinx/conf.py.in b/Utilities/Sphinx/conf.py.in index 67450e634b..590ccf4f0f 100644 --- a/Utilities/Sphinx/conf.py.in +++ b/Utilities/Sphinx/conf.py.in @@ -30,7 +30,10 @@ exclude_patterns = [ 'manual/presets/*.rst', ] -extensions = ['cmake'] +extensions = [ + 'cmake', + @conf_copybutton_ext@ +] templates_path = ['@conf_path@/templates'] nitpicky = True diff --git a/bootstrap b/bootstrap index 86b6486d92..1c11e76e75 100755 --- a/bootstrap +++ b/bootstrap @@ -85,6 +85,7 @@ cmake_bootstrap_debugger="" cmake_sphinx_info="" cmake_sphinx_man="" cmake_sphinx_html="" +cmake_sphinx_html_copybutton="" cmake_sphinx_qthelp="" cmake_sphinx_latexpdf="" cmake_sphinx_build="" @@ -736,13 +737,14 @@ Configuration: --debugger enable debugger support (default if supported) --no-debugger disable debugger support - --sphinx-info build Info manual with Sphinx - --sphinx-man build man pages with Sphinx - --sphinx-html build html help with Sphinx - --sphinx-qthelp build qch help with Sphinx - --sphinx-latexpdf build PDF with Sphinx using LaTeX - --sphinx-build= use as the sphinx-build executable - --sphinx-flags= pass to sphinx-build executable + --sphinx-info build Info manual with Sphinx + --sphinx-man build man pages with Sphinx + --sphinx-html build html help with Sphinx + --sphinx-html-copybutton build html help with the sphinx-copybutton extension + --sphinx-qthelp build qch help with Sphinx + --sphinx-latexpdf build PDF with Sphinx using LaTeX + --sphinx-build= use as the sphinx-build executable + --sphinx-flags= pass to sphinx-build executable Directory and file names: --prefix=PREFIX install files in tree rooted at PREFIX @@ -1004,6 +1006,7 @@ while test $# != 0; do --sphinx-info) cmake_sphinx_info="1" ;; --sphinx-man) cmake_sphinx_man="1" ;; --sphinx-html) cmake_sphinx_html="1" ;; + --sphinx-html-copybutton) cmake_sphinx_html_copybutton="1" ;; --sphinx-qthelp) cmake_sphinx_qthelp="1" ;; --sphinx-latexpdf) cmake_sphinx_latexpdf="1" ;; --sphinx-build=*) cmake_sphinx_build=`cmake_arg "$1"` ;; @@ -2018,6 +2021,11 @@ if test "x${cmake_bootstrap_debugger}" != "x"; then set (CMake_ENABLE_DEBUGGER '"${cmake_bootstrap_debugger}"' CACHE BOOL "Enable CMake debugger support" FORCE) ' >> "${cmake_bootstrap_dir}/InitialCacheFlags.cmake" fi +if test "x${cmake_sphinx_html_copybutton}" != "x"; then + echo ' +set (SPHINX_HTML_COPYBUTTON "'"${cmake_sphinx_html_copybutton}"'" CACHE BOOL "Build html help with the sphinx-copybutton extension" FORCE) +' >> "${cmake_bootstrap_dir}/InitialCacheFlags.cmake" +fi if test "x${cmake_sphinx_info}" != "x"; then echo ' set (SPHINX_INFO "'"${cmake_sphinx_info}"'" CACHE BOOL "Build Info manual with Sphinx" FORCE)