From 45a426a4e33b152fdb24698af85f0a115869eaeb Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 20 Aug 2026 17:26:34 -0400 Subject: [PATCH 1/7] codespell: Fix some hyphenated spellings These were surfaced by an updated `codespell` in the `spellcheck` CI base image. --- Help/command/find_package.rst | 2 +- Source/cmFindPackageCommand.cxx | 2 +- Tests/CPackComponentsForAll/CMakeLists.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) 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/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) From 59875d4a0831aa0647e7e4f78507066d629bb63e Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Fri, 21 Aug 2026 09:42:29 -0400 Subject: [PATCH 2/7] Tests/FindImageMagick: Tolerate pre-release versions The version installed from the system in our new Fedora 44 CI base image has a beta version of ImageMagick installed, which the FindImageMagick module can't parse. --- Tests/FindImageMagick/Test/main_magick++.cxx | 8 ++++++++ 1 file changed, 8 insertions(+) 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"; From ad5a65dd34fa95c5903029cba3ee3c64850a5dc8 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 20 Aug 2026 14:15:04 -0400 Subject: [PATCH 3/7] Utilities/Sphinx: Add option to build with copybutton The copy button is convenient for copying code blocks from CMake's documentation pages, and can be especially helpful when following the CMake tutorial. It is implemented optionally so that developers without the extension installed locally can still preview the site. Fixes: #28046 --- Utilities/Sphinx/CMakeLists.txt | 6 ++++++ Utilities/Sphinx/conf.py.in | 5 ++++- 2 files changed, 10 insertions(+), 1 deletion(-) 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 From 6e2301357ddf92c0b6e9b69a749872f3e546ed01 Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 20 Aug 2026 16:26:08 -0400 Subject: [PATCH 4/7] ci: Add sphinx-copybutton extension to Fedora base image Make it available to our documentation jobs. --- .gitlab/ci/docker/fedora44/deps_packages.lst | 1 + .gitlab/os-linux.yml | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) 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..b77056826b 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" From 1b1225a76633fad69fbb9e39573fc487af14d8e2 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 20 Aug 2026 15:28:43 -0400 Subject: [PATCH 5/7] ci: Enable Sphinx copybutton for cmake.org and Sphinx jobs --- .gitlab/ci/configure_sphinx.cmake | 1 + .gitlab/os-linux.yml | 1 + 2 files changed, 2 insertions(+) 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/os-linux.yml b/.gitlab/os-linux.yml index b77056826b..2d66350260 100644 --- a/.gitlab/os-linux.yml +++ b/.gitlab/os-linux.yml @@ -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 From 1c5e70c9d0ab65157ca7669a0a2c868710117d44 Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 20 Aug 2026 15:44:20 -0400 Subject: [PATCH 6/7] bootstrap: Add --sphinx-html-copybutton option Consistent with the SPHINX_HTML_COPYBUTTON CMake option. --- bootstrap | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) 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) From 392a79b91093970491b543e37210608e625a856b Mon Sep 17 00:00:00 2001 From: Tyler Yankee Date: Thu, 20 Aug 2026 16:03:53 -0400 Subject: [PATCH 7/7] Help/dev: Document use of sphinx-copybutton Add a section on third-party Sphinx extensions. While we're here, add a cross-reference on CMake's `README.rst`. --- Help/dev/documentation.rst | 18 ++++++++++++++++++ README.rst | 4 +++- 2 files changed, 21 insertions(+), 1 deletion(-) 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