diff --git a/docs/default.nix b/docs/default.nix index e67ce02..1ba0d3d 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -4,18 +4,37 @@ lib ? import ../lib/stdlib-extended.nix pkgs.lib inputs, ... }: let - nmd = import inputs.nmd { - inherit lib; - # The DocBook output of `nixos-render-docs` doesn't have the change - # `nmd` uses to work around the broken stylesheets in - # `docbook-xsl-ns`, so we restore the patched version here. - pkgs = - pkgs - // { - docbook-xsl-ns = - pkgs.docbook-xsl-ns.override {withManOptDedupPatch = true;}; - }; - }; + inherit (lib.modules) mkForce evalModules; + inherit (lib.strings) hasPrefix removePrefix; + inherit (lib.attrsets) isAttrs mapAttrs optionalAttrs recursiveUpdate isDerivation; + + # From home-manager: + # + # Recursively replace each derivation in the given attribute set + # with the same derivation but with the `outPath` attribute set to + # the string `"\${pkgs.attribute.path}"`. This allows the + # documentation to refer to derivations through their values without + # establishing an actual dependency on the derivation output. + # + # This is not 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}`. + scrubDerivations = prefixPath: attrs: let + scrubDerivation = name: value: let + pkgAttrName = prefixPath + "." + name; + in + if isAttrs value + then + scrubDerivations pkgAttrName value + // optionalAttrs (isDerivation value) { + outPath = "\${${pkgAttrName}}"; + } + else value; + in + mapAttrs scrubDerivation attrs; # Make sure the used package is scrubbed to avoid actually # instantiating derivations. @@ -23,30 +42,30 @@ imports = [ { _module.args = { - pkgs = lib.mkForce (nmd.scrubDerivations "pkgs" pkgs); - pkgs_i686 = lib.mkForce {}; + pkgs = mkForce (scrubDerivations "pkgs" pkgs); + pkgs_i686 = mkForce {}; }; } ]; }; - dontCheckDefinitions = {_module.check = false;}; - - githubDeclaration = user: repo: subpath: let - urlRef = "main"; - in { - url = "https://github.com/${user}/${repo}/blob/${urlRef}/${subpath}"; - name = "<${repo}/${subpath}>"; - }; - + # Specify the path to the module entrypoint nvimPath = toString ./..; - buildOptionsDocs = args @ { modules, includeModuleSystemOptions ? true, ... }: let - inherit ((lib.evalModules {inherit modules;})) options; + inherit ((evalModules {inherit modules;})) options; + + # Declaration of the Github site URL. + githubDeclaration = user: repo: subpath: let + urlRef = "github.com"; + branch = "main"; + in { + url = "https://${urlRef}/${user}/${repo}/blob/${branch}/${subpath}"; + name = "<${repo}/${subpath}>"; + }; in pkgs.buildPackages.nixosOptionsDoc ({ options = @@ -54,15 +73,14 @@ then options else builtins.removeAttrs options ["_module"]; transformOptions = opt: - opt - // { - # Clean up declaration sites to not refer to the Home Manager + recursiveUpdate opt { + # Clean up declaration sites to not refer to the neovim-flakee # source tree. declarations = map (decl: - if lib.hasPrefix nvimPath (toString decl) + if hasPrefix nvimPath (toString decl) then githubDeclaration "notashelf" "neovim-flake" - (lib.removePrefix "/" (lib.removePrefix nvimPath (toString decl))) + (removePrefix "/" (removePrefix nvimPath (toString decl))) else if decl == "lib/modules.nix" then # TODO: handle this in a better way (may require upstream @@ -86,6 +104,7 @@ release-config = builtins.fromJSON (builtins.readFile ../release.json); revision = "release-${release-config.release}"; + # Generate the `man home-configuration.nix` package nvf-configuration-manual = pkgs.runCommand "neovim-flake-reference-manpage" { @@ -95,12 +114,15 @@ # Generate manpages. mkdir -p $out/share/man/man5 mkdir -p $out/share/man/man1 + nixos-render-docs -j $NIX_BUILD_CORES options manpage \ --revision ${revision} \ ${nvimModuleDocs.optionsJSON}/share/doc/nixos/options.json \ $out/share/man/man5/neovim-flake.5 + cp ${./neovim-flake.1} $out/share/man/man1/neovim-flake.1 ''; + # Generate the HTML manual pages neovim-flake-manual = pkgs.callPackage ./manual.nix { inherit (inputs) nmd; @@ -110,6 +132,7 @@ neovim-flake = nvimModuleDocs.optionsJSON; }; }; + html = neovim-flake-manual; htmlOpenTool = pkgs.callPackage ./html-open-tool.nix {} {inherit html;}; in { @@ -120,7 +143,7 @@ in { # `nixosOptionsDoc` is more customizable. json = pkgs.runCommand "options.json" { - meta.description = "List of Home Manager options in JSON format"; + meta.description = "List of neovim-flake options in JSON format"; } '' mkdir -p $out/{share/doc,nix-support} cp -a ${nvimModuleDocs.optionsJSON}/share/doc/nixos $out/share/doc/neovim-flake