base: Merge pull request NixOS#213 from NixOS/update-description

Format using the base commit from nixfmt PR 217: NixOS/nixfmt@a98ea65

default.nix

@@ -1,6 +1,8 @@
-let requiredVersion = import ./lib/minver.nix; in
+let
+  requiredVersion = import ./lib/minver.nix;
+in
 
-if ! builtins ? nixVersion || builtins.compareVersions requiredVersion builtins.nixVersion == 1 then
+if !builtins ? nixVersion || builtins.compareVersions requiredVersion builtins.nixVersion == 1 then
 
   abort ''
 

doc/default.nix

@@ -1,4 +1,7 @@
-{ pkgs ? (import ./.. { }), nixpkgs ? { }}:
+{
+  pkgs ? (import ./.. { }),
+  nixpkgs ? { },
+}:
 let
   inherit (pkgs) lib;
   inherit (lib) hasPrefix removePrefix;
@@ -9,105 +12,174 @@ let
   lib-docs = import ./doc-support/lib-function-docs.nix {
     inherit pkgs nixpkgs;
     libsets = [
-      { name = "asserts"; description = "assertion functions"; }
-      { name = "attrsets"; description = "attribute set functions"; }
-      { name = "strings"; description = "string manipulation functions"; }
-      { name = "versions"; description = "version string functions"; }
-      { name = "trivial"; description = "miscellaneous functions"; }
-      { name = "fixedPoints"; baseName = "fixed-points"; description = "explicit recursion functions"; }
-      { name = "lists"; description = "list manipulation functions"; }
-      { name = "debug"; description = "debugging functions"; }
-      { name = "options"; description = "NixOS / nixpkgs option handling"; }
-      { name = "path"; description = "path functions"; }
-      { name = "filesystem"; description = "filesystem functions"; }
-      { name = "fileset"; description = "file set functions"; }
-      { name = "sources"; description = "source filtering functions"; }
-      { name = "cli"; description = "command-line serialization functions"; }
-      { name = "generators"; description = "functions that create file formats from nix data structures"; }
-      { name = "gvariant"; description = "GVariant formatted string serialization functions"; }
-      { name = "customisation"; description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets"; }
-      { name = "meta"; description = "functions for derivation metadata"; }
-      { name = "derivations"; description = "miscellaneous derivation-specific functions"; }
+      {
+        name = "asserts";
+        description = "assertion functions";
+      }
+      {
+        name = "attrsets";
+        description = "attribute set functions";
+      }
+      {
+        name = "strings";
+        description = "string manipulation functions";
+      }
+      {
+        name = "versions";
+        description = "version string functions";
+      }
+      {
+        name = "trivial";
+        description = "miscellaneous functions";
+      }
+      {
+        name = "fixedPoints";
+        baseName = "fixed-points";
+        description = "explicit recursion functions";
+      }
+      {
+        name = "lists";
+        description = "list manipulation functions";
+      }
+      {
+        name = "debug";
+        description = "debugging functions";
+      }
+      {
+        name = "options";
+        description = "NixOS / nixpkgs option handling";
+      }
+      {
+        name = "path";
+        description = "path functions";
+      }
+      {
+        name = "filesystem";
+        description = "filesystem functions";
+      }
+      {
+        name = "fileset";
+        description = "file set functions";
+      }
+      {
+        name = "sources";
+        description = "source filtering functions";
+      }
+      {
+        name = "cli";
+        description = "command-line serialization functions";
+      }
+      {
+        name = "generators";
+        description = "functions that create file formats from nix data structures";
+      }
+      {
+        name = "gvariant";
+        description = "GVariant formatted string serialization functions";
+      }
+      {
+        name = "customisation";
+        description = "Functions to customise (derivation-related) functions, derivatons, or attribute sets";
+      }
+      {
+        name = "meta";
+        description = "functions for derivation metadata";
+      }
+      {
+        name = "derivations";
+        description = "miscellaneous derivation-specific functions";
+      }
     ];
   };
 
-  epub = pkgs.runCommand "manual.epub" {
-    nativeBuildInputs = with pkgs; [ libxslt zip ];
-
-    epub = ''
-      <book xmlns="http://docbook.org/ns/docbook"
-            xmlns:xlink="http://www.w3.org/1999/xlink"
-            version="5.0"
-            xml:id="nixpkgs-manual">
-        <info>
-          <title>Nixpkgs Manual</title>
-          <subtitle>Version ${pkgs.lib.version}</subtitle>
-        </info>
-        <chapter>
-          <title>Temporarily unavailable</title>
-          <para>
-            The Nixpkgs manual is currently not available in EPUB format,
-            please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
-            instead.
-          </para>
-          <para>
-            If you've used the EPUB manual in the past and it has been useful to you, please
-            <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
-          </para>
-        </chapter>
-      </book>
-    '';
-
-    passAsFile = [ "epub" ];
-  } ''
-    mkdir scratch
-    xsltproc \
-      --param chapter.autolabel 0 \
-      --nonet \
-      --output scratch/ \
-      ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
-      $epubPath
-
-    echo "application/epub+zip" > mimetype
-    zip -0Xq "$out" mimetype
-    cd scratch && zip -Xr9D "$out" *
-  '';
+  epub =
+    pkgs.runCommand "manual.epub"
+      {
+        nativeBuildInputs = with pkgs; [
+          libxslt
+          zip
+        ];
+
+        epub = ''
+          <book xmlns="http://docbook.org/ns/docbook"
+                xmlns:xlink="http://www.w3.org/1999/xlink"
+                version="5.0"
+                xml:id="nixpkgs-manual">
+            <info>
+              <title>Nixpkgs Manual</title>
+              <subtitle>Version ${pkgs.lib.version}</subtitle>
+            </info>
+            <chapter>
+              <title>Temporarily unavailable</title>
+              <para>
+                The Nixpkgs manual is currently not available in EPUB format,
+                please use the <link xlink:href="https://nixos.org/nixpkgs/manual">HTML manual</link>
+                instead.
+              </para>
+              <para>
+                If you've used the EPUB manual in the past and it has been useful to you, please
+                <link xlink:href="https://github.com/NixOS/nixpkgs/issues/237234">let us know</link>.
+              </para>
+            </chapter>
+          </book>
+        '';
+
+        passAsFile = [ "epub" ];
+      }
+      ''
+        mkdir scratch
+        xsltproc \
+          --param chapter.autolabel 0 \
+          --nonet \
+          --output scratch/ \
+          ${pkgs.docbook_xsl_ns}/xml/xsl/docbook/epub/docbook.xsl \
+          $epubPath
+
+        echo "application/epub+zip" > mimetype
+        zip -0Xq "$out" mimetype
+        cd scratch && zip -Xr9D "$out" *
+      '';
 
   # NB: This file describes the Nixpkgs manual, which happens to use module
   #     docs infra originally developed for NixOS.
   optionsDoc = pkgs.nixosOptionsDoc {
-    inherit (pkgs.lib.evalModules {
-      modules = [ ../pkgs/top-level/config.nix ];
-      class = "nixpkgsConfig";
-    }) options;
+    inherit
+      (pkgs.lib.evalModules {
+        modules = [ ../pkgs/top-level/config.nix ];
+        class = "nixpkgsConfig";
+      })
+      options
+      ;
     documentType = "none";
-    transformOptions = opt:
-      opt // {
-        declarations =
-          map
-            (decl:
-              if hasPrefix (toString ../..) (toString decl)
-              then
-                let subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
-                in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; }
-              else decl)
-            opt.declarations;
-        };
+    transformOptions =
+      opt:
+      opt
+      // {
+        declarations = map (
+          decl:
+          if hasPrefix (toString ../..) (toString decl) then
+            let
+              subpath = removePrefix "/" (removePrefix (toString ../.) (toString decl));
+            in
+            {
+              url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}";
+              name = subpath;
+            }
+          else
+            decl
+        ) opt.declarations;
+      };
   };
-in pkgs.stdenv.mkDerivation {
+in
+pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
-  nativeBuildInputs = with pkgs; [
-    nixos-render-docs
-  ];
+  nativeBuildInputs = with pkgs; [ nixos-render-docs ];
 
   src = fs.toSource {
     root = ./.;
     fileset = fs.unions [
-      (fs.fileFilter (file:
-        file.hasExt "md"
-        || file.hasExt "md.in"
-      ) ./.)
+      (fs.fileFilter (file: file.hasExt "md" || file.hasExt "md.in") ./.)
       ./style.css
       ./anchor-use.js
       ./anchor.min.js
@@ -119,7 +191,7 @@ in pkgs.stdenv.mkDerivation {
     ln -s ${optionsDoc.optionsJSON}/share/doc/nixos/options.json ./config-options.json
   '';
 
-  pythonInterpreterTable = pkgs.callPackage ./doc-support/python-interpreter-table.nix {};
+  pythonInterpreterTable = pkgs.callPackage ./doc-support/python-interpreter-table.nix { };
 
   passAsFile = [ "pythonInterpreterTable" ];
 
@@ -172,25 +244,36 @@ in pkgs.stdenv.mkDerivation {
     echo "doc manual $dest nixpkgs-manual.epub" >> $out/nix-support/hydra-build-products
   '';
 
-  passthru.tests.manpage-urls = with pkgs; testers.invalidateFetcherByDrvHash
-    ({ name ? "manual_check-manpage-urls"
-     , script
-     , urlsFile
-     }: runCommand name {
-      nativeBuildInputs = [
-        cacert
-        (python3.withPackages (p: with p; [
-          aiohttp
-          rich
-          structlog
-        ]))
-      ];
-      outputHash = "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=";  # Empty output
-    } ''
-      python3 ${script} ${urlsFile}
-      touch $out
-    '') {
-      script = ./tests/manpage-urls.py;
-      urlsFile = ./manpage-urls.json;
-    };
+  passthru.tests.manpage-urls =
+    with pkgs;
+    testers.invalidateFetcherByDrvHash
+      (
+        {
+          name ? "manual_check-manpage-urls",
+          script,
+          urlsFile,
+        }:
+        runCommand name
+          {
+            nativeBuildInputs = [
+              cacert
+              (python3.withPackages (
+                p: with p; [
+                  aiohttp
+                  rich
+                  structlog
+                ]
+              ))
+            ];
+            outputHash = "sha256-47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU="; # Empty output
+          }
+          ''
+            python3 ${script} ${urlsFile}
+            touch $out
+          ''
+      )
+      {
+        script = ./tests/manpage-urls.py;
+        urlsFile = ./manpage-urls.json;
+      };
 }

doc/doc-support/lib-function-docs.nix

@@ -1,6 +1,10 @@
 # Generates the documentation for library functions via nixdoc.
 
-{ pkgs, nixpkgs, libsets }:
+{
+  pkgs,
+  nixpkgs,
+  libsets,
+}:
 
 with pkgs;
 
@@ -32,9 +36,16 @@ stdenv.mkDerivation {
     ```{=include=} sections auto-id-prefix=auto-generated
     EOF
 
-    ${lib.concatMapStrings ({ name, baseName ? name, description }: ''
-      docgen ${name} ${baseName} ${lib.escapeShellArg description}
-    '') libsets}
+    ${lib.concatMapStrings (
+      {
+        name,
+        baseName ? name,
+        description,
+      }:
+      ''
+        docgen ${name} ${baseName} ${lib.escapeShellArg description}
+      ''
+    ) libsets}
 
     echo '```' >> "$out/index.md"
   '';