nixos/manual: disallow docbook option docs

it's been long in the making, and with 23.05 out we can finally disable
docbook option docs and default to markdown instead. this brings a
massive speed boost in manual and manpage builds, so much so that we may
consider enabling user module documentation by default.

we don't remove the docbook support code entirely yet because it's a lot
all over, and probably better removed in multiple separate changes.

1 files changed, 5 insertions, 1 deletions

diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix
index a2385582a014..e4d9a6ebcc71 100644
--- a/nixos/lib/make-options-doc/default.nix
+++ b/nixos/lib/make-options-doc/default.nix
@@ -39,12 +39,16 @@
 # allow docbook option docs if `true`. only markdown documentation is allowed when set to
 # `false`, and a different renderer may be used with different bugs and performance
 # characteristics but (hopefully) indistinguishable output.
-, allowDocBook ? true
+# deprecated since 23.11.
+# TODO remove in a while.
+, allowDocBook ? false
 # whether lib.mdDoc is required for descriptions to be read as markdown.
 # !!! when this is eventually flipped to true, `lib.doRename` should also default to emitting Markdown
 , markdownByDefault ? false
 }:
 
+assert ! allowDocBook;
+
 let
   rawOpts = lib.optionAttrSetToDocList options;
   transformedOpts = map transformOptions rawOpts;