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