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

@@ -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}")

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