From 69aa2c2e10857ce76359278930f89026c19a4c14 Mon Sep 17 00:00:00 2001 From: Chris Patterson Date: Thu, 6 Jun 2024 09:08:02 -0400 Subject: [PATCH] build(doc): generate manpages only with -DGENERATE_MANPAGES=1 As pointed out by Noah in #15, Debian packaging lints issues in the generated manpage due to formatting emitted by older versions of pandoc: https://github.com/jgm/pandoc/issues/9020 While changes in recent versions of pandoc have improved the output, let's just take the generated output from pandoc 3.2 as a starting point and maintain it manually for the time being. This reduces friction for packaging and gives us flexibility if we wanted to do something in the manpage that pandoc doesn't support. Allow manpages to be generated at build-time with -DGENERATE_MANPAGES=1 which will make it easy to sync. Signed-off-by: Chris Patterson --- .github/workflows/main.yml | 20 +++++++++++--- cmake/doc.cmake | 41 ++++++++++++++++++----------- doc/azure-nvme-id.1 | 54 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 97 insertions(+), 18 deletions(-) create mode 100644 doc/azure-nvme-id.1 diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index f46b1a7..1411157 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -29,12 +29,26 @@ jobs: sudo apt install gcc pandoc cmake -y - name: Build & install project with cmake run: | - cmake . - make - sudo make install + cmake -B build -S . + make -C build + sudo make -C build install - name: Verify installation run: | test -f /usr/local/sbin/azure-nvme-id test -f /usr/local/share/man/man1/azure-nvme-id.1 test -f /usr/local/lib/udev/rules.d/80-azure-nvme.rules azure-nvme-id --version + - name: Verify manpage generation options + run: | + if grep -c "Pandoc" /usr/local/share/man/man1/azure-nvme-id.1; then echo "manpage unexpectedly generated by pandoc by default"; exit 1; fi + rm -rf build + cmake -DGENERATE_MANPAGES=0 -B build -S . + make -C build + sudo make -C build install + if grep -c "Pandoc" /usr/local/share/man/man1/azure-nvme-id.1; then echo "manpage unexpectedly generated by pandoc with -DGENERATE_MANPAGES=0"; exit 1; fi + rm -rf build + cmake -DGENERATE_MANPAGES=1 -B build -S . + make -C build + sudo make -C build install + if ! grep -c "Pandoc" /usr/local/share/man/man1/azure-nvme-id.1; then echo "manpage not generated by pandoc with -DGENERATE_MANPAGES=1"; exit 1; fi + diff --git a/cmake/doc.cmake b/cmake/doc.cmake index b080206..acb9b86 100644 --- a/cmake/doc.cmake +++ b/cmake/doc.cmake @@ -1,23 +1,34 @@ -find_program(PANDOC_EXECUTABLE pandoc) -if(NOT PANDOC_EXECUTABLE) +string(TIMESTAMP TODAY "%B %d, %Y") + +option(GENERATE_MANPAGES "Generate manpages with pandoc" OFF) +if(GENERATE_MANPAGES) + find_program(PANDOC_EXECUTABLE pandoc) + if(NOT PANDOC_EXECUTABLE) message(WARNING "Pandoc not found, will not generate manpages") return() + endif() + + add_custom_command( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1 + COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/doc + COMMAND ${PANDOC_EXECUTABLE} + ${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md + --standalone --from markdown --to man + --variable footer="azure-nvme-id ${VERSION}" + --variable date="${TODAY}" + -o ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1 + DEPENDS ${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md + COMMENT "Generating manpage for azure-nvme-id" + ) +else() + configure_file( + "${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.1" + "${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1" + @ONLY + ) endif() -string(TIMESTAMP TODAY "%B %d, %Y") -add_custom_command( - OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1 - COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_CURRENT_BINARY_DIR}/doc - COMMAND ${PANDOC_EXECUTABLE} - ${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md - --standalone --from markdown --to man - --variable footer="azure-nvme-id ${VERSION}" - --variable date="${TODAY}" - -o ${CMAKE_CURRENT_BINARY_DIR}/doc/azure-nvme-id.1 - DEPENDS ${CMAKE_SOURCE_DIR}/doc/azure-nvme-id.md - COMMENT "Generating manpage for azure-nvme-id" -) add_custom_target( doc ALL diff --git a/doc/azure-nvme-id.1 b/doc/azure-nvme-id.1 new file mode 100644 index 0000000..f46add7 --- /dev/null +++ b/doc/azure-nvme-id.1 @@ -0,0 +1,54 @@ +.TH "azure\-nvme\-id" "1" "@TODAY@" "azure-nvme-id\ @VERSION@" "User Manual" +.SH NAME +azure\-nvme\-id \- Identify Azure NVMe devices. +.SH SYNOPSIS +\f[B]azure\-nvme\-id\f[R] [\-\-debug] [\-\-help | \-\-version | +\-\-udev] +.SH DESCRIPTION +\f[B]azure\-nvme\-id\f[R] is a utility to identify Azure NVMe devices. +.PP +It performs an Identify Namespace command on the NVMe namespaces, +parsing metadata available in the vendor\-specific (vs) field which +contains various identification details with a comma\-separated, +key=value format. +.SH OPTIONS +.TP +\f[CR]\-\-help\f[R] +Show usage information and exit. +.TP +\f[CR]\-\-version\f[R] +Show version information and exit. +.TP +\f[CR]\-\-udev\f[R] +Run in udev mode, printing a set of \f[CR]=\f[R] variables +consumed by udev rules. +Requires DEVNAME to be set in environment. +.SH EXAMPLES +Identify NVMe namespaces: +.IP +.EX +$ sudo azure\-nvme\-id +/dev/nvme0n1: +/dev/nvme1n1: type=local,index=1,name=nvme\-110G\-1 +.EE +.PP +Parse device identifiers for udev consumption: +.IP +.EX +$ sudo env DEVNAME=/dev/nvme1n1 azure\-nvme\-id \-\-udev +AZURE_NVME_VS=type=local,index=1,name=nvme\-110G\-1 +AZURE_NVME_TYPE=local +AZURE_NVME_INDEX=1 +AZURE_NVME_NAME=nvme\-110G\-1 +.EE +.PP +Check \f[CR]azure\-nvme\-id\f[R] version: +.IP +.EX +$ azure\-nvme\-id \-\-version +azure\-nvme\-id 0.1.2 +.EE +.SH SEE ALSO +Source and documentation available at: \c +.UR https://github.com/Azure/azure-nvme-utils +.UE \c