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`.
This commit is contained in:
Tyler Yankee
2026-08-21 09:43:48 -04:00
parent 1c5e70c9d0
commit 392a79b910
2 changed files with 21 additions and 1 deletions
+18
View File
@@ -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
-----------------
+3 -1
View File
@@ -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