doc: make HTML manual build optional

Add `html-manual` Meson option to allow building manpages without the
HTML manual, removing the mdbook dependency for manpage-only builds.

Changes:
- Add `html-manual` Meson option (default: true)
- Make HTML manual build conditional in meson.build
- Add `buildHtmlManual` parameter to package.nix
- Conditional outputs: ["out" "man"] when enabled, ["out"] when disabled
- Make mdbook/rsync/json-schema-for-humans dependencies conditional
- Add `nix-manual-manpages-only` package variant

This allows systems that only need manpages to avoid the mdbook build
dependency while preserving full functionality for HTML manual builds.

doc/manual/meson.build

@@ -21,9 +21,13 @@ endif
 
 nix = find_program('nix', native : true)
 
-mdbook = find_program('mdbook', native : true)
 bash = find_program('bash', native : true)
+
+# HTML manual dependencies (conditional)
+if get_option('html-manual')
+  mdbook = find_program('mdbook', native : true)
   rsync = find_program('rsync', required : true, native : true)
+endif
 
 pymod = import('python')
 python = pymod.find_installation('python3')
@@ -109,6 +113,8 @@ else
   nix_input = []
 endif
 
+# HTML manual build (conditional)
+if get_option('html-manual')
   manual = custom_target(
     'manual',
     command : [
@@ -158,6 +164,7 @@ manual = custom_target(
       'markdown',
     ],
     depfile : 'manual.d',
+    build_by_default : true,
     env : {
       'RUST_LOG' : 'info',
       'MDBOOK_SUBSTITUTE_SEARCH' : meson.current_build_dir() / 'source',
@@ -170,6 +177,7 @@ install_subdir(
     manual_html.full_path(),
     install_dir : get_option('datadir') / 'doc/nix',
   )
+endif
 
 nix_nested_manpages = [
   [

doc/manual/meson.options

@@ -4,3 +4,10 @@ option(
   value : true,
   description : 'Whether this is an official release build (affects documentation URLs)',
 )
+
+option(
+  'html-manual',
+  type : 'boolean',
+  value : true,
+  description : 'Whether to build the HTML manual (requires mdbook)',
+)

doc/manual/package.nix

@@ -19,6 +19,11 @@
   # Configuration Options
 
   version,
+  /**
+    Whether to build the HTML manual.
+    When false, only manpages are built, avoiding the mdbook dependency.
+  */
+  buildHtmlManual ? true,
 
   # `tests` attribute
   testers,
@@ -57,9 +62,22 @@ mkMesonDerivation (finalAttrs: {
       ../../doc/manual/package.nix;
 
   # TODO the man pages should probably be separate
-  outputs = [
+  outputs =
+    if buildHtmlManual then
+      [
         "out"
         "man"
+      ]
+    else
+      [ "out" ]; # Only one output when HTML manual is disabled; use "out" for manpages
+
+  # When HTML manual is disabled, install manpages to "out" instead of "man"
+  mesonFlags = [
+    (lib.mesonBool "official-release" officialRelease)
+    (lib.mesonBool "html-manual" buildHtmlManual)
+  ]
+  ++ lib.optionals (!buildHtmlManual) [
+    "--mandir=${placeholder "out"}/share/man"
   ];
 
   nativeBuildInputs = [
@@ -67,41 +85,40 @@ mkMesonDerivation (finalAttrs: {
     meson
     ninja
     (lib.getBin lowdown-unsandboxed)
-    mdbook
     jq
     python3
+  ]
+  ++ lib.optionals buildHtmlManual [
+    mdbook
     rsync
     json-schema-for-humans
-    changelog-d
   ]
-  ++ lib.optionals (!officialRelease) [
+  ++ lib.optionals (!officialRelease && buildHtmlManual) [
     # When not an official release, we likely have changelog entries that have
     # yet to be rendered.
     # When released, these are rendered into a committed file to save a dependency.
     changelog-d
   ];
 
-  mesonFlags = [
-    (lib.mesonBool "official-release" officialRelease)
-  ];
-
   preConfigure = ''
     chmod u+w ./.version
     echo ${finalAttrs.version} > ./.version
   '';
 
-  postInstall = ''
+  postInstall = lib.optionalString buildHtmlManual ''
     mkdir -p ''$out/nix-support
     echo "doc manual ''$out/share/doc/nix/manual" >> ''$out/nix-support/hydra-build-products
   '';
 
+  passthru = lib.optionalAttrs buildHtmlManual {
     /**
       The root of the HTML manual.
       E.g. "${nix-manual.site}/index.html" exists.
     */
-  passthru.site = finalAttrs.finalPackage + "/share/doc/nix/manual";
 
-  passthru.tests =
+    site = finalAttrs.finalPackage + "/share/doc/nix/manual";
+
+    tests =
       let
         redirect-targets = callPackage ./redirect-targets-html.nix { };
       in
@@ -129,6 +146,7 @@ mkMesonDerivation (finalAttrs: {
           };
         };
       };
+  };
 
   meta = {
     platforms = lib.platforms.all;

doc/manual/source/protocols/json/meson.build

@@ -35,6 +35,7 @@ endforeach
 
 json_schema_generated_files = []
 
+if json_schema_for_humans.found()
   # Generate markdown documentation from JSON schema
   # Note: output must be just a filename, not a path
   gen_file = custom_target(
@@ -55,7 +56,6 @@ gen_file = custom_target(
   )
 
   idx = 0
-if json_schema_for_humans.found()
   foreach schema_name : schemas
     #schema_file = 'schema' / schema_name + '.yaml'
 

flake.nix

@@ -369,6 +369,7 @@
           # TODO probably should be `nix-cli`
           nix = self.packages.${system}.nix-everything;
           nix-manual = nixpkgsFor.${system}.native.nixComponents2.nix-manual;
+          nix-manual-manpages-only = nixpkgsFor.${system}.native.nixComponents2.nix-manual-manpages-only;
           nix-internal-api-docs = nixpkgsFor.${system}.native.nixComponents2.nix-internal-api-docs;
           nix-external-api-docs = nixpkgsFor.${system}.native.nixComponents2.nix-external-api-docs;
         }

packaging/components.nix

@@ -429,6 +429,15 @@ in
     The manual as would be published on https://nix.dev/reference/nix-manual
   */
   nix-manual = callPackage ../doc/manual/package.nix { version = fineVersion; };
+
+  /**
+    Manpages only (no HTML manual, no mdbook dependency)
+  */
+  nix-manual-manpages-only = callPackage ../doc/manual/package.nix {
+    version = fineVersion;
+    buildHtmlManual = false;
+  };
+
   /**
     Doxygen pages for C++ code
   */

packaging/hydra.nix

@@ -70,6 +70,7 @@ let
       ]
       ++ lib.optionals enableDocs [
         "nix-manual"
+        "nix-manual-manpages-only"
         "nix-internal-api-docs"
         "nix-external-api-docs"
       ]