fish-shell/cmake/Docs.cmake

find_program(SPHINX_EXECUTABLE NAMES sphinx-build
    HINTS
    $ENV{SPHINX_DIR}
    PATH_SUFFIXES bin
    DOC "Sphinx documentation generator")

include(FeatureSummary)

set(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc_src")
set(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")
set(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")
set(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")
set(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")
set(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")

# sphinx-docs uses fish_indent for highlighting.
# Prepend the output dir of fish_indent to PATH.
add_custom_target(sphinx-docs
    mkdir -p ${SPHINX_HTML_DIR}/_static/
    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${SPHINX_SRC_DIR}/_static/pygments.css ${SPHINX_HTML_DIR}/_static/
    COMMAND ${CMAKE_COMMAND} -E copy_if_different ${SPHINX_SRC_DIR}/_static/custom.css ${SPHINX_HTML_DIR}/_static/
    COMMAND env PATH="$<TARGET_FILE_DIR:fish_indent>:$$PATH"
        ${SPHINX_EXECUTABLE}
        -q -b html
        -c "${SPHINX_SRC_DIR}"
        -d "${SPHINX_CACHE_DIR}"
        "${SPHINX_SRC_DIR}"
        "${SPHINX_HTML_DIR}"
    DEPENDS ${SPHINX_SRC_DIR}/fish_indent_lexer.py fish_indent
    COMMENT "Building HTML documentation with Sphinx")

# sphinx-manpages needs the fish_indent binary for the version number
add_custom_target(sphinx-manpages
    env PATH="$<TARGET_FILE_DIR:fish_indent>:$$PATH"
        ${SPHINX_EXECUTABLE}
        -q -b man
        -c "${SPHINX_SRC_DIR}"
        -d "${SPHINX_CACHE_DIR}"
        "${SPHINX_SRC_DIR}"
        # TODO: This only works if we only have section 1 manpages.
        "${SPHINX_MANPAGE_DIR}/man1"
    DEPENDS fish_indent
    COMMENT "Building man pages with Sphinx")

if(SPHINX_EXECUTABLE)
    option(BUILD_DOCS "build documentation (requires Sphinx)" ON)
else(SPHINX_EXECUTABLE)
    option(BUILD_DOCS "build documentation (requires Sphinx)" OFF)
endif(SPHINX_EXECUTABLE)

if(BUILD_DOCS AND NOT SPHINX_EXECUTABLE)
    message(FATAL_ERROR "build documentation selected, but sphinx-build could not be found")
endif()

if(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/html
   AND IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/man)
    set(HAVE_PREBUILT_DOCS TRUE)
else()
    set(HAVE_PREBUILT_DOCS FALSE)
endif()

if(BUILD_DOCS OR HAVE_PREBUILT_DOCS)
    set(INSTALL_DOCS ON)
else()
    set(INSTALL_DOCS OFF)
endif()

add_feature_info(Documentation INSTALL_DOCS "user manual and documentation")

if(BUILD_DOCS)
    configure_file("${SPHINX_SRC_DIR}/conf.py" "${SPHINX_BUILD_DIR}/conf.py" @ONLY)
    add_custom_target(doc ALL
                      DEPENDS sphinx-docs sphinx-manpages)

    # Group docs targets into a DocsTargets folder
    set_property(TARGET doc sphinx-docs sphinx-manpages
                 PROPERTY FOLDER cmake/DocTargets)

elseif(HAVE_PREBUILT_DOCS)
    if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR)
        # Out of tree build - link the prebuilt documentation to the build tree
        add_custom_target(link_doc ALL)
        add_custom_command(TARGET link_doc
            COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/user_doc ${CMAKE_CURRENT_BINARY_DIR}/user_doc
            POST_BUILD)
    endif()
endif(BUILD_DOCS)
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`find_program(SPHINX_EXECUTABLE NAMES sphinx-build`
Initial sphinx file import 2018-12-16 00:23:36 +00:00			`HINTS`
			`$ENV{SPHINX_DIR}`
			`PATH_SUFFIXES bin`
			`DOC "Sphinx documentation generator")`

Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`include(FeatureSummary)`
[cmake] make building documentation optional Add a BUILD_DOCS option which is contingent on Doxygen being present, and only build the documentation if this is enabled. 2018-01-14 13:16:11 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`set(SPHINX_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/doc_src")`
			`set(SPHINX_ROOT_DIR "${CMAKE_CURRENT_BINARY_DIR}/user_doc")`
			`set(SPHINX_BUILD_DIR "${SPHINX_ROOT_DIR}/build")`
			`set(SPHINX_CACHE_DIR "${SPHINX_ROOT_DIR}/doctrees")`
			`set(SPHINX_HTML_DIR "${SPHINX_ROOT_DIR}/html")`
			`set(SPHINX_MANPAGE_DIR "${SPHINX_ROOT_DIR}/man")`
Initial sphinx file import 2018-12-16 00:23:36 +00:00
Teach CMake to tell Sphinx where fish_indent is 2019-03-14 20:50:35 +00:00			`# sphinx-docs uses fish_indent for highlighting.`
			`# Prepend the output dir of fish_indent to PATH.`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`add_custom_target(sphinx-docs`
Fix clean build of sphinx-docs 2019-10-20 06:15:58 +00:00			`mkdir -p ${SPHINX_HTML_DIR}/_static/`
			`COMMAND ${CMAKE_COMMAND} -E copy_if_different ${SPHINX_SRC_DIR}/_static/pygments.css ${SPHINX_HTML_DIR}/_static/`
sphinx: honor changes in static html assets Also fix custom.css. 2019-10-15 19:59:37 +00:00			`COMMAND ${CMAKE_COMMAND} -E copy_if_different ${SPHINX_SRC_DIR}/_static/custom.css ${SPHINX_HTML_DIR}/_static/`
			`COMMAND env PATH="$<TARGET_FILE_DIR:fish_indent>:$$PATH"`
Teach CMake to tell Sphinx where fish_indent is 2019-03-14 20:50:35 +00:00			`${SPHINX_EXECUTABLE}`
Initial sphinx file import 2018-12-16 00:23:36 +00:00			`-q -b html`
			`-c "${SPHINX_SRC_DIR}"`
			`-d "${SPHINX_CACHE_DIR}"`
			`"${SPHINX_SRC_DIR}"`
			`"${SPHINX_HTML_DIR}"`
We no longer have two doc systems, move sphinx_doc_src back to doc_src 2020-02-20 01:00:35 +00:00			`DEPENDS ${SPHINX_SRC_DIR}/fish_indent_lexer.py fish_indent`
Initial sphinx file import 2018-12-16 00:23:36 +00:00			`COMMENT "Building HTML documentation with Sphinx")`

cmake: sphinx-manpages requires fish_indent for version number Fixes issue #6216. Problem introduced in 3b8505bebeebd79c9cd3a3aa39a7404725db985a. 2019-09-21 08:32:14 +00:00			`# sphinx-manpages needs the fish_indent binary for the version number`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`add_custom_target(sphinx-manpages`
cmake: sphinx-manpages requires fish_indent for version number Fixes issue #6216. Problem introduced in 3b8505bebeebd79c9cd3a3aa39a7404725db985a. 2019-09-21 08:32:14 +00:00			`env PATH="$<TARGET_FILE_DIR:fish_indent>:$$PATH"`
			`${SPHINX_EXECUTABLE}`
Initial sphinx file import 2018-12-16 00:23:36 +00:00			`-q -b man`
			`-c "${SPHINX_SRC_DIR}"`
			`-d "${SPHINX_CACHE_DIR}"`
			`"${SPHINX_SRC_DIR}"`
Fix manpage directory This installed files in man/ directly, instead of in man/man1/, so they weren't installed. See #5696. 2019-02-25 20:12:08 +00:00			`# TODO: This only works if we only have section 1 manpages.`
			`"${SPHINX_MANPAGE_DIR}/man1"`
cmake: sphinx-manpages requires fish_indent for version number Fixes issue #6216. Problem introduced in 3b8505bebeebd79c9cd3a3aa39a7404725db985a. 2019-09-21 08:32:14 +00:00			`DEPENDS fish_indent`
Initial sphinx file import 2018-12-16 00:23:36 +00:00			`COMMENT "Building man pages with Sphinx")`

Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`if(SPHINX_EXECUTABLE)`
			`option(BUILD_DOCS "build documentation (requires Sphinx)" ON)`
			`else(SPHINX_EXECUTABLE)`
			`option(BUILD_DOCS "build documentation (requires Sphinx)" OFF)`
			`endif(SPHINX_EXECUTABLE)`
[cmake] make building documentation optional Add a BUILD_DOCS option which is contingent on Doxygen being present, and only build the documentation if this is enabled. 2018-01-14 13:16:11 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`if(BUILD_DOCS AND NOT SPHINX_EXECUTABLE)`
			`message(FATAL_ERROR "build documentation selected, but sphinx-build could not be found")`
			`endif()`
[cmake] copy shipped documentation files if they exist Enables documentation in tarballs to be installed, even if Doxygen isn't present. 2018-02-01 14:46:15 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`if(IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/html`
cmake: fix prebuilt documentation detection and installation 2019-03-04 14:06:07 +00:00			`AND IS_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/user_doc/man)`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`set(HAVE_PREBUILT_DOCS TRUE)`
			`else()`
			`set(HAVE_PREBUILT_DOCS FALSE)`
			`endif()`
[cmake] copy shipped documentation files if they exist Enables documentation in tarballs to be installed, even if Doxygen isn't present. 2018-02-01 14:46:15 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`if(BUILD_DOCS OR HAVE_PREBUILT_DOCS)`
			`set(INSTALL_DOCS ON)`
			`else()`
			`set(INSTALL_DOCS OFF)`
			`endif()`
[cmake] copy shipped documentation files if they exist Enables documentation in tarballs to be installed, even if Doxygen isn't present. 2018-02-01 14:46:15 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`add_feature_info(Documentation INSTALL_DOCS "user manual and documentation")`
[cmake] make building documentation optional Add a BUILD_DOCS option which is contingent on Doxygen being present, and only build the documentation if this is enabled. 2018-01-14 13:16:11 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`if(BUILD_DOCS)`
			`configure_file("${SPHINX_SRC_DIR}/conf.py" "${SPHINX_BUILD_DIR}/conf.py" @ONLY)`
			`add_custom_target(doc ALL`
Remove last vestiges of Doxygen from Docs.cmake 2019-02-25 03:02:39 +00:00			`DEPENDS sphinx-docs sphinx-manpages)`
[cmake] make building documentation optional Add a BUILD_DOCS option which is contingent on Doxygen being present, and only build the documentation if this is enabled. 2018-01-14 13:16:11 +00:00
			`# Group docs targets into a DocsTargets folder`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`set_property(TARGET doc sphinx-docs sphinx-manpages`
[cmake] make building documentation optional Add a BUILD_DOCS option which is contingent on Doxygen being present, and only build the documentation if this is enabled. 2018-01-14 13:16:11 +00:00			`PROPERTY FOLDER cmake/DocTargets)`
Remove last vestiges of Doxygen from Docs.cmake 2019-02-25 03:02:39 +00:00
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`elseif(HAVE_PREBUILT_DOCS)`
			`if(NOT CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_CURRENT_BINARY_DIR)`
[cmake] support prebuilt documentation in out-of-tree builds 2018-03-24 14:34:30 +00:00			`# Out of tree build - link the prebuilt documentation to the build tree`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`add_custom_target(link_doc ALL)`
			`add_custom_command(TARGET link_doc`
[cmake] support prebuilt documentation in out-of-tree builds 2018-03-24 14:34:30 +00:00			`COMMAND ${CMAKE_COMMAND} -E create_symlink ${CMAKE_CURRENT_SOURCE_DIR}/user_doc ${CMAKE_CURRENT_BINARY_DIR}/user_doc`
			`POST_BUILD)`
Use lowercase CMake function names This is a best practice to distinguish them from variables. 2020-03-14 23:11:35 +00:00			`endif()`
			`endif(BUILD_DOCS)`