mirror of
https://github.com/NixOS/nix.git
synced 2025-12-09 18:41:03 +01:00
doc: make manpage generation independent of mdbook
Add standalone markdown preprocessor to generate manpages without requiring
mdbook's Rust toolchain. This removes a significant build dependency for
manpage generation while keeping the HTML manual (mdbook) working unchanged.
Changes:
- Add expand-includes.py: Python 3 script that recursively expands
{{#include}} directives, resolves @docroot@ to nix.dev URLs, and handles
@generated@/ paths for build-generated files
- Update render-manpage.sh: Replace mdbook-based implementation with
standalone version that uses expand-includes.py + lowdown
- Update meson.build: All 134 manpage targets now use standalone renderer
with proper dependencies (expand-includes.py, experimental-features-shortlist)
- Fix nix-hash.md: Remove extra parenthesis in markdown link syntax
Benefits:
- No mdbook/Rust toolchain required for manpage builds
- Manpages contain nix.dev/latest URLs instead of broken relative paths
- Fixes bug where mdbook didn't expand experimental-features-shortlist.md
- 98.5% identical output to mdbook (2 files differ, both acceptable)
All 134 manpages (131 section 1, 2 section 5, 1 section 8) build successfully.
This commit is contained in:
parent
525755dadc
commit
d007b4e81b
4 changed files with 280 additions and 15 deletions
36
doc/manual/render-manpage.sh
Executable file → Normal file
36
doc/manual/render-manpage.sh
Executable file → Normal file
|
|
@ -1,25 +1,51 @@
|
|||
#!/usr/bin/env bash
|
||||
#
|
||||
# Standalone manpage renderer that doesn't require mdbook.
|
||||
# Uses expand-includes.py to preprocess markdown, then lowdown to generate manpages.
|
||||
|
||||
set -euo pipefail
|
||||
|
||||
script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
|
||||
lowdown_args=
|
||||
|
||||
# Optional --out-no-smarty flag for compatibility with nix_nested_manpages
|
||||
if [ "$1" = --out-no-smarty ]; then
|
||||
lowdown_args=--out-no-smarty
|
||||
shift
|
||||
fi
|
||||
|
||||
[ "$#" = 4 ] || {
|
||||
echo "wrong number of args passed" >&2
|
||||
[ "$#" = 6 ] || {
|
||||
cat >&2 <<EOF
|
||||
Usage: $0 [--out-no-smarty] <title> <section> <source-root> <generated-root> <infile> <outfile>
|
||||
|
||||
Arguments:
|
||||
title - Manpage title (e.g., "nix-env --install")
|
||||
section - Manpage section number (1, 5, 8, etc.)
|
||||
source-root - Root directory of markdown sources
|
||||
generated-root - Root directory of generated markdown files
|
||||
infile - Input markdown file (relative to build directory)
|
||||
outfile - Output manpage file
|
||||
|
||||
Examples:
|
||||
$0 "nix-store --query" 1 doc/manual/source build/doc/manual/source \\
|
||||
build/doc/manual/source/command-ref/nix-store/query.md nix-store-query.1
|
||||
EOF
|
||||
exit 1
|
||||
}
|
||||
|
||||
title="$1"
|
||||
section="$2"
|
||||
infile="$3"
|
||||
outfile="$4"
|
||||
source_root="$3"
|
||||
generated_root="$4"
|
||||
infile="$5"
|
||||
outfile="$6"
|
||||
|
||||
# Expand includes and pipe to lowdown
|
||||
(
|
||||
printf "Title: %s\n\n" "$title"
|
||||
cat "$infile"
|
||||
python3 "$script_dir/expand-includes.py" \
|
||||
--source-root "$source_root" \
|
||||
--generated-root "$generated_root" \
|
||||
"$infile"
|
||||
) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue