diff --git a/doc/manual/expand-includes.py b/doc/manual/expand-includes.py index ed182b946..59c687f23 100644 --- a/doc/manual/expand-includes.py +++ b/doc/manual/expand-includes.py @@ -91,7 +91,7 @@ def expand_includes( return ''.join(lines) -def resolve_docroot(content: str, current_file: Path, source_root: Path) -> str: +def resolve_docroot(content: str, current_file: Path, source_root: Path, docroot_url: str) -> str: """ Replace @docroot@ with nix.dev URL and convert .md to .html. @@ -99,10 +99,6 @@ def resolve_docroot(content: str, current_file: Path, source_root: Path) -> str: manpages are viewed standalone. lowdown will display these as proper references in the manpage output. """ - # Use the latest nix.dev documentation URL - # This matches what users would actually want to reference from a manpage - docroot_url = "https://nix.dev/manual/nix/latest" - # Replace @docroot@ with the base URL content = content.replace("@docroot@", docroot_url) @@ -126,6 +122,7 @@ def process_file( input_file: Path, source_root: Path, generated_root: Path | None, + docroot_url: str, ) -> str: """Process a single markdown file.""" content = input_file.read_text() @@ -134,7 +131,7 @@ def process_file( content = expand_includes(content, input_file, source_root, generated_root) # Resolve @docroot@ references - content = resolve_docroot(content, input_file, source_root) + content = resolve_docroot(content, input_file, source_root, docroot_url) # Resolve @_at_ escapes content = resolve_at_escapes(content) @@ -181,6 +178,12 @@ Examples: type=Path, help="Output file (default: stdout)", ) + parser.add_argument( + "-u", "--doc-url", + type=str, + default="https://nix.dev/manual/nix/latest", + help="Base URL for documentation links (default: https://nix.dev/manual/nix/latest)", + ) args = parser.parse_args() @@ -199,7 +202,7 @@ Examples: try: # Process the file - output = process_file(args.input_file, args.source_root, args.generated_root) + output = process_file(args.input_file, args.source_root, args.generated_root, args.doc_url) # Write output if args.output: diff --git a/doc/manual/meson.build b/doc/manual/meson.build index cda419c44..b809cf473 100644 --- a/doc/manual/meson.build +++ b/doc/manual/meson.build @@ -5,6 +5,20 @@ project( license : 'LGPL-2.1-or-later', ) +# Compute documentation URL based on version and release type +version = meson.project_version() +official_release = get_option('official-release') + +if official_release + # For official releases, use versioned URL (dropping patch version) + version_parts = version.split('.') + major_minor = '@0@.@1@'.format(version_parts[0], version_parts[1]) + doc_url = 'https://nix.dev/manual/nix/@0@'.format(major_minor) +else + # For development builds, use /latest + doc_url = 'https://nix.dev/manual/nix/latest' +endif + nix = find_program('nix', native : true) mdbook = find_program('mdbook', native : true) @@ -215,6 +229,7 @@ foreach command : nix_nested_manpages section, meson.current_source_dir() / 'source', meson.current_build_dir() / 'source', + doc_url, meson.current_source_dir() / 'source/command-ref' / command[0] / (page + '.md'), '@OUTPUT0@', ], @@ -334,6 +349,7 @@ foreach page : nix3_manpages section, meson.current_source_dir() / 'source', meson.current_build_dir() / 'source', + doc_url, meson.current_build_dir() / 'source/command-ref/new-cli/@0@.md'.format( page, ), @@ -390,6 +406,7 @@ foreach entry : nix_manpages section, meson.current_source_dir() / 'source', meson.current_build_dir() / 'source', + doc_url, input_file, '@OUTPUT@', ], diff --git a/doc/manual/meson.options b/doc/manual/meson.options new file mode 100644 index 000000000..8bd27104f --- /dev/null +++ b/doc/manual/meson.options @@ -0,0 +1,6 @@ +option( + 'official-release', + type : 'boolean', + value : true, + description : 'Whether this is an official release build (affects documentation URLs)', +) diff --git a/doc/manual/package.nix b/doc/manual/package.nix index 78c4aa825..cbe422cab 100644 --- a/doc/manual/package.nix +++ b/doc/manual/package.nix @@ -81,6 +81,10 @@ mkMesonDerivation (finalAttrs: { changelog-d ]; + mesonFlags = [ + (lib.mesonBool "official-release" officialRelease) + ]; + preConfigure = '' chmod u+w ./.version echo ${finalAttrs.version} > ./.version diff --git a/doc/manual/render-manpage.sh b/doc/manual/render-manpage.sh index 325dd98da..6577809b0 100644 --- a/doc/manual/render-manpage.sh +++ b/doc/manual/render-manpage.sh @@ -15,20 +15,22 @@ if [ "$1" = --out-no-smarty ]; then shift fi -[ "$#" = 6 ] || { +[ "$#" = 7 ] || { cat >&2 <
+Usage: $0 [--out-no-smarty] <section> <source-root> <generated-root> <doc-url> <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 + doc-url - Base URL for documentation links 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 \\ + https://nix.dev/manual/nix/latest \\ build/doc/manual/source/command-ref/nix-store/query.md nix-store-query.1 EOF exit 1 @@ -38,8 +40,9 @@ title="$1" section="$2" source_root="$3" generated_root="$4" -infile="$5" -outfile="$6" +doc_url="$5" +infile="$6" +outfile="$7" # Expand includes and pipe to lowdown ( @@ -47,5 +50,6 @@ outfile="$6" python3 "$script_dir/expand-includes.py" \ --source-root "$source_root" \ --generated-root "$generated_root" \ + --doc-url "$doc_url" \ "$infile" ) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"