From 74ab2ba05cc813fdc36ca8b518a113b402e92ac9 Mon Sep 17 00:00:00 2001 From: Joel Rosdahl Date: Sun, 28 Sep 2025 19:24:30 +0200 Subject: [PATCH] docs: Generate documention in Markdown format as well --- .github/workflows/build.yaml | 2 +- doc/CMakeLists.txt | 59 +++++++++++++++++++----------- doc/INSTALL.md | 8 ++-- doc/scripts/generate-html | 20 ++++++++++ doc/scripts/generate-manpage | 27 ++++++++++++++ doc/scripts/generate-markdown | 27 ++++++++++++++ misc/Makefile.posix-binary-release | 8 ++-- 7 files changed, 121 insertions(+), 30 deletions(-) create mode 100755 doc/scripts/generate-html create mode 100755 doc/scripts/generate-manpage create mode 100755 doc/scripts/generate-markdown diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f964b990..303e0ec5 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -271,7 +271,7 @@ jobs: uses: actions/checkout@v4 - name: Prepare environment run: | - sudo apt-get install -y asciidoctor + sudo apt-get install -y asciidoctor pandoc - name: Build documentation run: ci/build-docs - name: Upload documentation diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 1d860f2b..d77cea67 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -1,43 +1,42 @@ find_program(ASCIIDOCTOR_EXE asciidoctor) mark_as_advanced(ASCIIDOCTOR_EXE) # Don't show in CMake UIs +find_program(PANDOC_EXE pandoc) +mark_as_advanced(PANDOC_EXE) # Don't show in CMake UIs + if(NOT ASCIIDOCTOR_EXE) message(WARNING "Could not find asciidoctor; documentation will not be generated") else() - function(generate_doc backend adoc_file output_file) + function(generate_doc type adoc_file output_file) add_custom_command( OUTPUT "${output_file}" COMMAND - ${ASCIIDOCTOR_EXE} - -o "${output_file}" - -a revnumber="${CCACHE_VERSION}" - -a icons=font - -a toc=left - -a sectanchors - -a stylesheet="${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css" - -b "${backend}" - "${CMAKE_SOURCE_DIR}/${adoc_file}" + "${CMAKE_CURRENT_SOURCE_DIR}/scripts/generate-${type}" + "${ASCIIDOCTOR_EXE}" + "${PANDOC_EXE}" + "${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css" + "${CCACHE_VERSION}" + "${CMAKE_SOURCE_DIR}/${adoc_file}" + "${output_file}" MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/${adoc_file}" DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/ccache-doc.css" ) - if(${backend} STREQUAL manpage) - # Convert monospace to bold since that's typically rendered better when - # viewing the man page. - add_custom_command( - OUTPUT "${output_file}" - COMMAND perl -pi -e "'s!\\\\f\\(CR(.*?)\\\\fP!\\\\fB\\1\\\\fP!g'" "${output_file}" - APPEND - ) - endif() - if("${backend}" STREQUAL manpage) + + if("${type}" STREQUAL manpage) install( FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}" DESTINATION "${CMAKE_INSTALL_MANDIR}/man1" ) - else() + elseif("${type}" STREQUAL html) set(html_doc_files "${html_doc_files}" "${output_file}" PARENT_SCOPE) install( - FILES "${CMAKE_SOURCE_DIR}/${adoc_file}" "${CMAKE_CURRENT_BINARY_DIR}/${output_file}" + FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}" + DESTINATION "${CMAKE_INSTALL_DOCDIR}" + ) + elseif("${type}" STREQUAL markdown) + set(markdown_doc_files "${markdown_doc_files}" "${output_file}" PARENT_SCOPE) + install( + FILES "${CMAKE_CURRENT_BINARY_DIR}/${output_file}" DESTINATION "${CMAKE_INSTALL_DOCDIR}" ) endif() @@ -52,6 +51,19 @@ else() generate_doc(html doc/NEWS.adoc NEWS.html) add_custom_target(doc-html DEPENDS "${html_doc_files}") + if(PANDOC_EXE) + # + # Markdown documentation + # + generate_doc(markdown LICENSE.adoc LICENSE.md) + generate_doc(markdown doc/AUTHORS.adoc AUTHORS.md) + generate_doc(markdown doc/MANUAL.adoc MANUAL.md) + generate_doc(markdown doc/NEWS.adoc NEWS.md) + add_custom_target(doc-markdown DEPENDS "${markdown_doc_files}") + else() + message(WARNING "Could not find pandoc; markdown documentation will not be generated") + endif() + # # Man page # @@ -59,4 +71,7 @@ else() add_custom_target(doc-man-page DEPENDS ccache.1) add_custom_target(doc ALL DEPENDS doc-html doc-man-page) + if(PANDOC_EXE) + add_dependencies(doc doc-markdown) + endif() endif() diff --git a/doc/INSTALL.md b/doc/INSTALL.md index fb3fdcd3..08a55da7 100644 --- a/doc/INSTALL.md +++ b/doc/INSTALL.md @@ -13,9 +13,11 @@ To build ccache you need: Optional: -- GNU Bourne Again SHell (bash) for tests. -- [Asciidoctor](https://asciidoctor.org) to build the HTML documentation. -- [Python](https://www.python.org) to debug and run the performance test suite. +- [Bash](https://www.gnu.org/software/bash) and [Python](https://www.python.org) + to run the test suite. +- [Asciidoctor](https://asciidoctor.org) to build documentation in HTML and + Markdown format. +- [Pandoc](https://pandoc.org) to build documentation in Markdown format. See also [CI configurations](../.github/workflows/build.yaml) for regularly tested build setups, including cross-compilation and dependencies required in diff --git a/doc/scripts/generate-html b/doc/scripts/generate-html new file mode 100755 index 00000000..ce60a768 --- /dev/null +++ b/doc/scripts/generate-html @@ -0,0 +1,20 @@ +#!/bin/bash + +set -euo pipefail + +asciidoctor=$1 +pandoc=$2 +stylesheet=$3 +version=$4 +input=$5 +output=$6 + +"${asciidoctor}" \ + -a revnumber="${version}" \ + -a icons=font \ + -a toc=left \ + -a sectanchors \ + -a stylesheet="${stylesheet}" \ + -b html \ + -o "${output}" \ + "${input}" diff --git a/doc/scripts/generate-manpage b/doc/scripts/generate-manpage new file mode 100755 index 00000000..10795bde --- /dev/null +++ b/doc/scripts/generate-manpage @@ -0,0 +1,27 @@ +#!/bin/bash + +set -euo pipefail + +asciidoctor=$1 +pandoc=$2 +stylesheet=$3 +version=$4 +input=$5 +output=$6 + +tmpfile=$(mktemp) +trap 'rm -f "${tmpfile}"' EXIT + +"${asciidoctor}" \ + -a revnumber="${version}" \ + -a icons=font \ + -a toc=left \ + -a sectanchors \ + -a stylesheet="${stylesheet}" \ + -b manpage \ + -o "${tmpfile}" \ + "${input}" + +# Convert monospace to bold since that's typically rendered better when viewing +# the man page. +perl -pe "'s!\\\\f\\(CR(.*?)\\\\fP!\\\\fB\\1\\\\fP!g'" "${tmpfile}" >"${output}" diff --git a/doc/scripts/generate-markdown b/doc/scripts/generate-markdown new file mode 100755 index 00000000..c180d05c --- /dev/null +++ b/doc/scripts/generate-markdown @@ -0,0 +1,27 @@ +#!/bin/bash + +set -euo pipefail + +asciidoctor=$1 +pandoc=$2 +stylesheet=$3 +version=$4 +input=$5 +output=$6 + +tmpfile=$(mktemp) +trap 'rm -f "${tmpfile}"' EXIT + +"${asciidoctor}" \ + -a revnumber="${version}" \ + -a icons=font \ + -a toc=left \ + -a sectanchors \ + -a stylesheet="${stylesheet}" \ + -b docbook \ + -o "${tmpfile}" \ + "${input}" + +# "\\-" -> "- " in tables, "-" otherwise +pandoc -f docbook -t markdown "${tmpfile}" | \ + sed -e 's/\\- /- /' -e 's/\\-/-/' >"${output}" diff --git a/misc/Makefile.posix-binary-release b/misc/Makefile.posix-binary-release index da8c8c8b..1d7a7b49 100644 --- a/misc/Makefile.posix-binary-release +++ b/misc/Makefile.posix-binary-release @@ -9,14 +9,14 @@ sysconfdir = $(prefix)/etc default_sysconfdir = /usr/local/etc doc_files = \ - LICENSE.adoc \ + LICENSE.md \ LICENSE.html \ - MANUAL.adoc \ + MANUAL.md \ MANUAL.html \ - NEWS.adoc \ + NEWS.md \ NEWS.html \ GPL-3.0.txt \ - LICENSE.adoc \ + LICENSE.md \ README.md PYTHON = python3 -- 2.47.3