diff options
| author | Vincent Ambo <mail@tazj.in> | 2018-12-30 01:10:19 +0100 |
|---|---|---|
| committer | Frederik Rietdijk <freddyrietdijk@fridh.nl> | 2019-01-04 11:28:27 +0100 |
| commit | 0c99dac49735d3a7c20d231c4d7b1dc057bc81df (patch) | |
| tree | a45072f55fc1c27189c95285d17512c3632a7bb3 | |
| parent | eab0c3258ff90ee1023b2488e2237b315d8d486b (diff) | |
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.
| -rw-r--r-- | doc/default.nix | 5 | ||||
| -rw-r--r-- | doc/functions/library.xml | 9 | ||||
| -rw-r--r-- | doc/lib-function-docs.nix | 26 |
3 files changed, 38 insertions, 2 deletions
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' + ''; +} |