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 /doc | |
| parent | eab0c3258ff90ee1023b2488e2237b315d8d486b (diff) | |
| download | nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar.gz nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar.bz2 nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar.lz nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar.xz nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.tar.zst nixpkgs-0c99dac49735d3a7c20d231c4d7b1dc057bc81df.zip | |
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.
Diffstat (limited to 'doc')
| -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 98b4b92be52..7ceaec28af3 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 901423c52a1..b01de3c6e41 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 00000000000..421f848d25a --- /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' + ''; +} |