From 0c99dac49735d3a7c20d231c4d7b1dc057bc81df Mon Sep 17 00:00:00 2001
From: Vincent Ambo <mail@tazj.in>
Date: Sun, 30 Dec 2018 01:10:19 +0100
Subject: [PATCH] doc: Add automatic generation of library function
 documentation

Modifies the build process of the manual to invoke nixdoc
automatically to generate XML files with function documentation.

Currently documentation is present for five of the files in `lib/`.

To add another file to the generated docs, both
`doc/functions/library.xml` and `doc/lib-function-docs.nix` must be
updated.
---
 doc/default.nix           |  5 +++--
 doc/functions/library.xml |  9 +++++++++
 doc/lib-function-docs.nix | 26 ++++++++++++++++++++++++++
 3 files changed, 38 insertions(+), 2 deletions(-)
 create mode 100644 doc/lib-function-docs.nix

diff --git a/doc/default.nix b/doc/default.nix
index 98b4b92be524..7ceaec28af38 100644
--- a/doc/default.nix
+++ b/doc/default.nix
@@ -2,8 +2,8 @@
 let
   lib = pkgs.lib;
   locationsXml = import ./lib-function-locations.nix { inherit pkgs nixpkgs; };
-in
-pkgs.stdenv.mkDerivation {
+  functionDocs = import ./lib-function-docs.nix { inherit locationsXml pkgs; };
+in pkgs.stdenv.mkDerivation {
   name = "nixpkgs-manual";
 
   buildInputs = with pkgs; [ pandoc libxml2 libxslt zip jing  xmlformat ];
@@ -32,6 +32,7 @@ pkgs.stdenv.mkDerivation {
   postPatch = ''
     rm -rf ./functions/library/locations.xml
     ln -s ${locationsXml} ./functions/library/locations.xml
+    ln -s ${functionDocs} ./functions/library/generated
     echo ${lib.version} > .version
   '';
 
diff --git a/doc/functions/library.xml b/doc/functions/library.xml
index 901423c52a18..b01de3c6e413 100644
--- a/doc/functions/library.xml
+++ b/doc/functions/library.xml
@@ -12,4 +12,13 @@
  <xi:include href="./library/asserts.xml" />
 
  <xi:include href="./library/attrsets.xml" />
+
+ <!-- These docs are generated via nixdoc. To add another generated
+      library function file to this list, the file
+      `lib-function-docs.nix` must also be updated. -->
+ <xi:include href="./library/generated/strings.xml" />
+ <xi:include href="./library/generated/trivial.xml" />
+ <xi:include href="./library/generated/lists.xml" />
+ <xi:include href="./library/generated/debug.xml" />
+ <xi:include href="./library/generated/options.xml" />
 </section>
diff --git a/doc/lib-function-docs.nix b/doc/lib-function-docs.nix
new file mode 100644
index 000000000000..421f848d25ab
--- /dev/null
+++ b/doc/lib-function-docs.nix
@@ -0,0 +1,26 @@
+# Generates the documentation for library functons via nixdoc. To add
+# another library function file to this list, the include list in the
+# file `doc/functions/library.xml` must also be updated.
+
+{ pkgs ? import ./.. {}, locationsXml }:
+
+with pkgs; stdenv.mkDerivation {
+  name = "nixpkgs-lib-docs";
+  src = ./../lib;
+
+  buildInputs = [ nixdoc ];
+  installPhase = ''
+    function docgen {
+      nixdoc -c "$1" -d "$2" -f "../lib/$1.nix"  > "$out/$1.xml"
+    }
+
+    mkdir -p $out
+    ln -s ${locationsXml} $out/locations.xml
+
+    docgen strings 'String manipulation functions'
+    docgen trivial 'Miscellaneous functions'
+    docgen lists 'List manipulation functions'
+    docgen debug 'Debugging functions'
+    docgen options 'NixOS / nixpkgs option handling'
+  '';
+}