Skip to content

Commit

Permalink
build(doc): generate manpages only with -DGENERATE_MANPAGES=1
Browse files Browse the repository at this point in the history
As pointed out by Noah in Azure#15, Debian packaging lints issues in the
generated manpage due to formatting emitted by older versions of pandoc:
jgm/pandoc#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 <[email protected]>
  • Loading branch information
cjp256 committed Jun 6, 2024
1 parent a20550e commit 69aa2c2
Show file tree
Hide file tree
Showing 3 changed files with 97 additions and 18 deletions.
20 changes: 17 additions & 3 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
41 changes: 26 additions & 15 deletions cmake/doc.cmake
Original file line number Diff line number Diff line change
@@ -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
Expand Down
54 changes: 54 additions & 0 deletions doc/azure-nvme-id.1
Original file line number Diff line number Diff line change
@@ -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]<key>=<value>\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

0 comments on commit 69aa2c2

Please sign in to comment.