Andrew Geissler | c926e17 | 2021-05-07 16:11:35 -0500 | [diff] [blame^] | 1 | From aebabafe085dd1b84027a1e31e5566c82528bd62 Mon Sep 17 00:00:00 2001 |
| 2 | From: Bastian Krause <bst@pengutronix.de> |
| 3 | Date: Tue, 4 May 2021 11:41:56 +0200 |
| 4 | Subject: [PATCH] doc: allow disabling docs/man page generation |
| 5 | |
| 6 | The assumption that HTML documentation and manual pages should be |
| 7 | generated if the required tools (asciidoc) are present is not always |
| 8 | true. So add a cmake option that allows disabling the docs/man page |
| 9 | generation. The default is to generate docs/man pages like before. |
| 10 | |
| 11 | Origin: https://github.com/ccache/ccache/pull/844 |
| 12 | Upstream-Status: Submitted |
| 13 | Signed-off-by: Bastian Krause <bst@pengutronix.de> |
| 14 | --- |
| 15 | doc/CMakeLists.txt | 128 +++++++++++++++++++++++---------------------- |
| 16 | 1 file changed, 66 insertions(+), 62 deletions(-) |
| 17 | |
| 18 | diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt |
| 19 | index c5ce224d..74b7831b 100644 |
| 20 | --- a/doc/CMakeLists.txt |
| 21 | +++ b/doc/CMakeLists.txt |
| 22 | @@ -1,70 +1,74 @@ |
| 23 | +option(BUILD_DOCS "Indicates whether HTML documentation and manual pages should be built or not" ON) |
| 24 | + |
| 25 | find_program(ASCIIDOC_EXE asciidoc) |
| 26 | mark_as_advanced(ASCIIDOC_EXE) # Don't show in CMake UIs |
| 27 | |
| 28 | -if(NOT ASCIIDOC_EXE) |
| 29 | - message(WARNING "Could not find asciidoc; documentation will not be generated") |
| 30 | -else() |
| 31 | - # |
| 32 | - # HTML documentation |
| 33 | - # |
| 34 | - function(generate_html adoc_file) |
| 35 | - get_filename_component(base_name "${adoc_file}" NAME_WE) |
| 36 | - set(html_file "${base_name}.html") |
| 37 | - add_custom_command( |
| 38 | - OUTPUT "${html_file}" |
| 39 | - COMMAND |
| 40 | - ${ASCIIDOC_EXE} |
| 41 | - -o "${html_file}" |
| 42 | - -a revnumber="${CCACHE_VERSION}" |
| 43 | - -a toc |
| 44 | - -b xhtml11 |
| 45 | - "${CMAKE_SOURCE_DIR}/${adoc_file}" |
| 46 | - MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/${adoc_file}" |
| 47 | - ) |
| 48 | - set(html_files "${html_files}" "${html_file}" PARENT_SCOPE) |
| 49 | - endfunction() |
| 50 | +if (BUILD_DOCS) |
| 51 | + if(NOT ASCIIDOC_EXE) |
| 52 | + message(WARNING "Could not find asciidoc; documentation will not be generated") |
| 53 | + else() |
| 54 | + # |
| 55 | + # HTML documentation |
| 56 | + # |
| 57 | + function(generate_html adoc_file) |
| 58 | + get_filename_component(base_name "${adoc_file}" NAME_WE) |
| 59 | + set(html_file "${base_name}.html") |
| 60 | + add_custom_command( |
| 61 | + OUTPUT "${html_file}" |
| 62 | + COMMAND |
| 63 | + ${ASCIIDOC_EXE} |
| 64 | + -o "${html_file}" |
| 65 | + -a revnumber="${CCACHE_VERSION}" |
| 66 | + -a toc |
| 67 | + -b xhtml11 |
| 68 | + "${CMAKE_SOURCE_DIR}/${adoc_file}" |
| 69 | + MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/${adoc_file}" |
| 70 | + ) |
| 71 | + set(html_files "${html_files}" "${html_file}" PARENT_SCOPE) |
| 72 | + endfunction() |
| 73 | |
| 74 | - generate_html(LICENSE.adoc) |
| 75 | - generate_html(doc/AUTHORS.adoc) |
| 76 | - generate_html(doc/MANUAL.adoc) |
| 77 | - generate_html(doc/NEWS.adoc) |
| 78 | + generate_html(LICENSE.adoc) |
| 79 | + generate_html(doc/AUTHORS.adoc) |
| 80 | + generate_html(doc/MANUAL.adoc) |
| 81 | + generate_html(doc/NEWS.adoc) |
| 82 | |
| 83 | - add_custom_target(doc-html DEPENDS "${html_files}") |
| 84 | - set(doc_files "${html_files}") |
| 85 | + add_custom_target(doc-html DEPENDS "${html_files}") |
| 86 | + set(doc_files "${html_files}") |
| 87 | |
| 88 | - # |
| 89 | - # Man page |
| 90 | - # |
| 91 | - find_program(A2X_EXE a2x) |
| 92 | - mark_as_advanced(A2X_EXE) # Don't show in CMake UIs |
| 93 | - if(NOT A2X_EXE) |
| 94 | - message(WARNING "Could not find a2x; man page will not be generated") |
| 95 | - else() |
| 96 | - # MANUAL.adoc -> MANUAL.xml -> man page |
| 97 | - add_custom_command( |
| 98 | - OUTPUT MANUAL.xml |
| 99 | - COMMAND |
| 100 | - ${ASCIIDOC_EXE} |
| 101 | - -o - |
| 102 | - -a revnumber=${CCACHE_VERSION} |
| 103 | - -d manpage |
| 104 | - -b docbook "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" |
| 105 | - | perl -pe 's!<literal>\(.*?\)</literal>!<emphasis role="strong">\\1</emphasis>!g' |
| 106 | - >MANUAL.xml |
| 107 | - MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" |
| 108 | - ) |
| 109 | - add_custom_command( |
| 110 | - OUTPUT ccache.1 |
| 111 | - COMMAND ${A2X_EXE} --doctype manpage --format manpage MANUAL.xml |
| 112 | - MAIN_DEPENDENCY MANUAL.xml |
| 113 | - ) |
| 114 | - add_custom_target(doc-man-page DEPENDS ccache.1) |
| 115 | - install( |
| 116 | - FILES "${CMAKE_CURRENT_BINARY_DIR}/ccache.1" |
| 117 | - DESTINATION "${CMAKE_INSTALL_MANDIR}/man1" |
| 118 | - ) |
| 119 | - set(doc_files "${doc_files}" ccache.1) |
| 120 | - endif() |
| 121 | + # |
| 122 | + # Man page |
| 123 | + # |
| 124 | + find_program(A2X_EXE a2x) |
| 125 | + mark_as_advanced(A2X_EXE) # Don't show in CMake UIs |
| 126 | + if(NOT A2X_EXE) |
| 127 | + message(WARNING "Could not find a2x; man page will not be generated") |
| 128 | + else() |
| 129 | + # MANUAL.adoc -> MANUAL.xml -> man page |
| 130 | + add_custom_command( |
| 131 | + OUTPUT MANUAL.xml |
| 132 | + COMMAND |
| 133 | + ${ASCIIDOC_EXE} |
| 134 | + -o - |
| 135 | + -a revnumber=${CCACHE_VERSION} |
| 136 | + -d manpage |
| 137 | + -b docbook "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" |
| 138 | + | perl -pe 's!<literal>\(.*?\)</literal>!<emphasis role="strong">\\1</emphasis>!g' |
| 139 | + >MANUAL.xml |
| 140 | + MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/doc/MANUAL.adoc" |
| 141 | + ) |
| 142 | + add_custom_command( |
| 143 | + OUTPUT ccache.1 |
| 144 | + COMMAND ${A2X_EXE} --doctype manpage --format manpage MANUAL.xml |
| 145 | + MAIN_DEPENDENCY MANUAL.xml |
| 146 | + ) |
| 147 | + add_custom_target(doc-man-page DEPENDS ccache.1) |
| 148 | + install( |
| 149 | + FILES "${CMAKE_CURRENT_BINARY_DIR}/ccache.1" |
| 150 | + DESTINATION "${CMAKE_INSTALL_MANDIR}/man1" |
| 151 | + ) |
| 152 | + set(doc_files "${doc_files}" ccache.1) |
| 153 | + endif() |
| 154 | |
| 155 | - add_custom_target(doc ALL DEPENDS "${doc_files}") |
| 156 | + add_custom_target(doc ALL DEPENDS "${doc_files}") |
| 157 | + endif() |
| 158 | endif() |
| 159 | -- |
| 160 | 2.29.2 |
| 161 | |