From 76ce9faca6e16d348afb9d78a1a13eb19c381b76 Mon Sep 17 00:00:00 2001 From: Emily Date: Thu, 22 Jun 2023 00:15:18 +0100 Subject: doc/manual: use `nixosOptionDoc` The only change to `options.json` are that the `declarations` fields now contain correct GitHub URLs. The changes to the HTML manual are all either strict improvements: * "Declared by:" links point to the correct URLs. * `lib.mdDoc` documentation is included. or else trivial: * Additional whitespace in the HTML source. * Some interchange of `
` and
  ``.
* Fancy quotes used in some type descriptions.

`optionsDocBook` is exported temporarily as it is used by
`nix-doc-munge` for the Markdown conversion process.

This drops support for building the manual on 22.11, which lacks a
complete implementation of this processor, and provides stubbed-out
manual packages with an explanation on that version.
---
 modules/documentation/default.nix | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

(limited to 'modules/documentation/default.nix')

diff --git a/modules/documentation/default.nix b/modules/documentation/default.nix
index 6bd3412..d741995 100644
--- a/modules/documentation/default.nix
+++ b/modules/documentation/default.nix
@@ -21,10 +21,11 @@ let
     It isn't perfect, but it seems to cover a vast majority of use cases.
     Caveat: even if the package is reached by a different means,
     the path above will be shown and not e.g. `${config.services.foo.package}`. */
-  manual = import ../../doc/manual rec {
+  realManual = import ../../doc/manual {
     inherit pkgs config;
     version = config.system.darwinVersion;
     revision = config.system.darwinRevision;
+    nixpkgsRevision = config.system.nixpkgsRevision;
     options =
       let
         scrubbedEval = evalModules {
@@ -43,6 +44,39 @@ let
       in scrubbedEval.options;
   };
 
+  # TODO: Remove this when dropping 22.11 support.
+  manual = realManual //
+    lib.optionalAttrs (lib.versionOlder lib.version "23.05-pre") rec {
+      optionsJSON = pkgs.writeTextFile {
+        name = "options.json-stub";
+        destination = "/share/doc/darwin/options.json";
+        text = "{}";
+      };
+      manpages = pkgs.writeTextFile {
+        name = "darwin-manpages-stub";
+        destination = "/share/man/man5/configuration.nix.5";
+        text = ''
+          .TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "Darwin" "Darwin Reference Pages"
+          .SH "NAME"
+          \fIconfiguration\&.nix\fP \- Darwin system configuration specification
+          .SH "DESCRIPTION"
+          .PP
+          The nix\-darwin documentation now requires nixpkgs 23.05 to build.
+        '';
+      };
+      manualHTML = pkgs.writeTextFile {
+        name = "darwin-manual-html-stub";
+        destination = "/share/doc/darwin/index.html";
+        text = ''
+          
+          Darwin Configuration Options
+          The nix-darwin documentation now requires nixpkgs 23.05 to build.
+        '';
+      };
+      manual = manualHTML;
+      manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
+    };
+
   helpScript = pkgs.writeScriptBin "darwin-help"
     ''
       #! ${pkgs.stdenv.shell} -e
-- 
cgit v1.2.3


From e65131e69cab1b18fb49b572b983a18720502e1b Mon Sep 17 00:00:00 2001
From: Emily 
Date: Thu, 22 Jun 2023 12:21:32 +0100
Subject: treewide: convert all option docs to Markdown

This process was automated by [my fork of `nix-doc-munge`]; thanks
to @pennae for writing this tool! It automatically checks that the
resulting documentation doesn't change, although my fork loosens
this a little to ignore some irrelevant whitespace and typographical
differences.

As of this commit there is no DocBook remaining in the options
documentation.

You can play along at home if you want to reproduce this commit:

    $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \
      nix shell nixpkgs#coreutils \
      -c find . -name '*.nix' \
      -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \
      {} +

[my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
---
 modules/documentation/default.nix | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'modules/documentation/default.nix')

diff --git a/modules/documentation/default.nix b/modules/documentation/default.nix
index d741995..7712a13 100644
--- a/modules/documentation/default.nix
+++ b/modules/documentation/default.nix
@@ -89,9 +89,9 @@ in
     documentation.enable = mkOption {
       type = types.bool;
       default = true;
-      description = ''
+      description = lib.mdDoc ''
         Whether to install documentation of packages from
-         into the generated system path.
+        {option}`environment.systemPackages` into the generated system path.
 
         See "Multiple-output packages" chapter in the nixpkgs manual for more info.
       '';
@@ -101,8 +101,8 @@ in
     documentation.man.enable = mkOption {
       type = types.bool;
       default = true;
-      description = ''
-        Whether to install manual pages and the man command.
+      description = lib.mdDoc ''
+        Whether to install manual pages and the {command}`man` command.
         This also includes "man" outputs.
       '';
     };
@@ -110,8 +110,8 @@ in
     documentation.info.enable = mkOption {
       type = types.bool;
       default = true;
-      description = ''
-        Whether to install info pages and the info command.
+      description = lib.mdDoc ''
+        Whether to install info pages and the {command}`info` command.
         This also includes "info" outputs.
       '';
     };
@@ -119,8 +119,8 @@ in
     documentation.doc.enable = mkOption {
       type = types.bool;
       default = true;
-      description = ''
-        Whether to install documentation distributed in packages' /share/doc.
+      description = lib.mdDoc ''
+        Whether to install documentation distributed in packages' `/share/doc`.
         Usually plain text and/or HTML.
         This also includes "doc" outputs.
       '';
-- 
cgit v1.2.3


From 69648c6cbbecf34c327d73e36b5aed32edfb9ed9 Mon Sep 17 00:00:00 2001
From: Emily 
Date: Sat, 24 Jun 2023 05:09:22 +0100
Subject: doc/manual: use `nixos-render-docs`

Now that all the DocBook documentation is gone, we can switch to the
new NixOS documentation generator. No meaningful change in HTML output,
except that I removed the rather pointless preface and changed the
title accordingly. Manual page output is greatly improved; it was
kind of broken before. The `sed` hack is pretty gross but I have
confirmed that nixpkgs will be happy to accept a PR to make things
a little more customizable.

This also drops the `manual` alias (deprecated in nixpkgs in 2018
and imported into nix-darwin), and `manualEpub` (because the NixOS
documentation generator doesn't support it and also nobody wants this
as an ebook).
---
 modules/documentation/default.nix | 1 -
 1 file changed, 1 deletion(-)

(limited to 'modules/documentation/default.nix')

diff --git a/modules/documentation/default.nix b/modules/documentation/default.nix
index 7712a13..a49d277 100644
--- a/modules/documentation/default.nix
+++ b/modules/documentation/default.nix
@@ -73,7 +73,6 @@ let
           The nix-darwin documentation now requires nixpkgs 23.05 to build.
         '';
       };
-      manual = manualHTML;
       manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
     };
 
-- 
cgit v1.2.3