1.. # Copyright (c) 2017-2021, Lawrence Livermore National Security, LLC and
2.. # other BLT Project Developers. See the top-level LICENSE file for details
3.. #
4.. # SPDX-License-Identifier: (BSD-3-Clause)
5
6Documenation Macros
7===================
8
9.. _blt_add_doxygen_target:
10
11blt_add_doxygen_target
12~~~~~~~~~~~~~~~~~~~~~~
13
14.. code-block:: cmake
15
16    blt_add_doxygen_target(doxygen_target_name)
17
18Creates a build target for invoking Doxygen to generate docs. Expects to
19find a ``Doxyfile.in`` in the directory the macro is called in.
20
21This macro sets up the doxygen paths so that the doc builds happen
22out of source. For ``make install``, this will place the resulting docs in
23``docs/doxygen/<doxygen_target_name>``.
24
25
26.. _blt_add_sphinx_target:
27
28blt_add_sphinx_target
29~~~~~~~~~~~~~~~~~~~~~
30
31.. code-block:: cmake
32
33    blt_add_sphinx_target(sphinx_target_name)
34
35Creates a build target for invoking Sphinx to generate docs. Expects
36to find a ``conf.py`` or ``conf.py.in`` in the directory the macro is called
37in. Requires that a CMake variable named ``SPHINX_EXECUTABLE``
38contains the path to the ``sphinx-build`` executable.
39
40If ``conf.py`` is found, it is directly used as input to Sphinx.
41
42If ``conf.py.in`` is found, this macro uses CMake's ``configure_file()`` command
43to generate a ``conf.py``, which is then used as input to Sphinx.
44
45This macro sets up the sphinx paths so that the doc builds happen
46out of source. For ``make install``, this will place the resulting docs in
47``docs/sphinx/<sphinx_target_name>``.
48