mirror of
https://gitlab.kitware.com/cmake/cmake.git
synced 2026-09-25 04:09:36 +03:00
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:
@@ -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 -S Utilities/Sphinx -B build -DSPHINX_HTML=ON -DSPHINX_MAN=ON
|
||||||
$ cmake --build build
|
$ 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
|
Markup Constructs
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
|||||||
+3
-1
@@ -57,12 +57,14 @@ generator and options. Then build it and install it.
|
|||||||
To build the documentation, install `Sphinx`_ and configure CMake with
|
To build the documentation, install `Sphinx`_ and configure CMake with
|
||||||
``-DSPHINX_HTML=ON`` and/or ``-DSPHINX_MAN=ON`` to enable the "html" or
|
``-DSPHINX_HTML=ON`` and/or ``-DSPHINX_MAN=ON`` to enable the "html" or
|
||||||
"man" builder. Add ``-DSPHINX_EXECUTABLE=/path/to/sphinx-build`` if the
|
"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
|
To run the test suite, run ``ctest`` in the CMake build directory after
|
||||||
building. See the `CMake Testing Guide`_ for details.
|
building. See the `CMake Testing Guide`_ for details.
|
||||||
|
|
||||||
.. _`Sphinx`: https://sphinx-doc.org
|
.. _`Sphinx`: https://sphinx-doc.org
|
||||||
|
.. _`CMake Documentation Guide`: Help/dev/documentation.rst
|
||||||
.. _`CMake Testing Guide`: Help/dev/testing.rst
|
.. _`CMake Testing Guide`: Help/dev/testing.rst
|
||||||
|
|
||||||
Building CMake from Scratch
|
Building CMake from Scratch
|
||||||
|
|||||||
Reference in New Issue
Block a user