mirrors/nix-darwin
1
0
Fork 0
mirror of https://github.com/LnL7/nix-darwin.git synced 2024-12-14 11:57:34 +00:00
Code Activity
nix-darwin/modules/documentation/default.nix

143 lines
4.3 KiB
Nix
Raw Normal View History

version: default Git revision options to `null` This allows for more uniform handling in the documentation generator, and avoids lying about the Git reference being `master` internally.
2023-07-07 08:02:38 +00:00
{ config, lib, pkgs, baseModules, modules, ... }:
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
with lib;
let
cfg = config.documentation;
modules/documentation/default.nix: Fix args warning
2021-12-20 21:49:23 +00:00
# To reference the regular configuration from inside the docs evaluation further down.
# While not strictly necessary, this extra binding avoids accidental name capture in
# the future.
regularConfig = config;
argsModule = {
Revert "eval-config: set `class`"
2023-07-24 22:24:20 +00:00
config._module.args = regularConfig._module.args // {
modules/documentation/default.nix: Fix args warning
2021-12-20 21:49:23 +00:00
modules = [ ];
Revert "eval-config: set `class`"
2023-07-24 22:24:20 +00:00
};
modules/documentation/default.nix: Fix args warning
2021-12-20 21:49:23 +00:00
};
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
/* For the purpose of generating docs, evaluate options with each derivation
in `pkgs` (recursively) replaced by a fake with path "\${pkgs.attribute.path}".
It isn't 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}`. */
doc/manual: use `nixosOptionDoc` The only change to `options.json` are that the `declarations` fields now contain correct GitHub URLs. The changes to the HTML manual are all either strict improvements: * "Declared by:" links point to the correct URLs. * `lib.mdDoc` documentation is included. or else trivial: * Additional whitespace in the HTML source. * Some interchange of `<pre class="programlisting">` and `<code class="literal">`. * Fancy quotes used in some type descriptions. `optionsDocBook` is exported temporarily as it is used by `nix-doc-munge` for the Markdown conversion process. This drops support for building the manual on 22.11, which lacks a complete implementation of this processor, and provides stubbed-out manual packages with an explanation on that version.
2023-06-21 23:15:18 +00:00
realManual = import ../../doc/manual {
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
inherit pkgs config;
doc: fix module references
2019-05-04 19:03:17 +00:00
version = config.system.darwinVersion;
revision = config.system.darwinRevision;
version: default Git revision options to `null` This allows for more uniform handling in the documentation generator, and avoids lying about the Git reference being `master` internally.
2023-07-07 08:02:38 +00:00
inherit (config.system) nixpkgsRevision;
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
options =
let
Revert "eval-config: set `class`"
2023-07-24 22:24:20 +00:00
scrubbedEval = evalModules {
modules = baseModules ++ [ argsModule ];
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
specialArgs = { pkgs = scrubDerivations "pkgs" pkgs; };
};
scrubDerivations = namePrefix: pkgSet: mapAttrs
(name: value:
let wholeName = "${namePrefix}.${name}"; in
if isAttrs value then
scrubDerivations wholeName value
// (optionalAttrs (isDerivation value) { outPath = "\${${wholeName}}"; })
else value
)
pkgSet;
in scrubbedEval.options;
};
doc/manual: use `nixosOptionDoc` The only change to `options.json` are that the `declarations` fields now contain correct GitHub URLs. The changes to the HTML manual are all either strict improvements: * "Declared by:" links point to the correct URLs. * `lib.mdDoc` documentation is included. or else trivial: * Additional whitespace in the HTML source. * Some interchange of `<pre class="programlisting">` and `<code class="literal">`. * Fancy quotes used in some type descriptions. `optionsDocBook` is exported temporarily as it is used by `nix-doc-munge` for the Markdown conversion process. This drops support for building the manual on 22.11, which lacks a complete implementation of this processor, and provides stubbed-out manual packages with an explanation on that version.
2023-06-21 23:15:18 +00:00
# TODO: Remove this when dropping 22.11 support.
manual = realManual //
documentation: use feature test for docs generator This should be less brittle than the version-based check, although arguably this kind of `lib.version` mismatch should break as early as possible... Fixes: #718
2023-07-07 00:30:20 +00:00
lib.optionalAttrs (!pkgs.buildPackages ? nixos-render-docs) rec {
doc/manual: use `nixosOptionDoc` The only change to `options.json` are that the `declarations` fields now contain correct GitHub URLs. The changes to the HTML manual are all either strict improvements: * "Declared by:" links point to the correct URLs. * `lib.mdDoc` documentation is included. or else trivial: * Additional whitespace in the HTML source. * Some interchange of `<pre class="programlisting">` and `<code class="literal">`. * Fancy quotes used in some type descriptions. `optionsDocBook` is exported temporarily as it is used by `nix-doc-munge` for the Markdown conversion process. This drops support for building the manual on 22.11, which lacks a complete implementation of this processor, and provides stubbed-out manual packages with an explanation on that version.
2023-06-21 23:15:18 +00:00
optionsJSON = pkgs.writeTextFile {
name = "options.json-stub";
destination = "/share/doc/darwin/options.json";
text = "{}";
};
manpages = pkgs.writeTextFile {
name = "darwin-manpages-stub";
destination = "/share/man/man5/configuration.nix.5";
text = ''
.TH "CONFIGURATION\&.NIX" "5" "01/01/1980" "Darwin" "Darwin Reference Pages"
.SH "NAME"
\fIconfiguration\&.nix\fP \- Darwin system configuration specification
.SH "DESCRIPTION"
.PP
The nix\-darwin documentation now requires nixpkgs 23.05 to build.
'';
};
manualHTML = pkgs.writeTextFile {
name = "darwin-manual-html-stub";
destination = "/share/doc/darwin/index.html";
text = ''
<!DOCTYPE html>
<title>Darwin Configuration Options</title>
The nix-darwin documentation now requires nixpkgs 23.05 to build.
'';
};
manualHTMLIndex = "${manualHTML}/share/doc/darwin/index.html";
};
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
helpScript = pkgs.writeScriptBin "darwin-help"
''
#! ${pkgs.stdenv.shell} -e
open ${manual.manualHTMLIndex}
'';
in
{
options = {
documentation.enable = mkOption {
type = types.bool;
default = true;
treewide: remove lib.mdDoc
2024-04-14 21:02:32 +00:00
description = ''
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
Whether to install documentation of packages from
treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
2023-06-22 11:21:32 +00:00
{option}`environment.systemPackages` into the generated system path.
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
See "Multiple-output packages" chapter in the nixpkgs manual for more info.
'';
# which is at ../../../doc/multiple-output.xml
};
documentation.man.enable = mkOption {
type = types.bool;
default = true;
treewide: remove lib.mdDoc
2024-04-14 21:02:32 +00:00
description = ''
treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
2023-06-22 11:21:32 +00:00
Whether to install manual pages and the {command}`man` command.
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
This also includes "man" outputs.
'';
};
documentation.info.enable = mkOption {
type = types.bool;
default = true;
treewide: remove lib.mdDoc
2024-04-14 21:02:32 +00:00
description = ''
treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
2023-06-22 11:21:32 +00:00
Whether to install info pages and the {command}`info` command.
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
This also includes "info" outputs.
'';
};
documentation.doc.enable = mkOption {
type = types.bool;
default = true;
treewide: remove lib.mdDoc
2024-04-14 21:02:32 +00:00
description = ''
treewide: convert all option docs to Markdown This process was automated by [my fork of `nix-doc-munge`]; thanks to @pennae for writing this tool! It automatically checks that the resulting documentation doesn't change, although my fork loosens this a little to ignore some irrelevant whitespace and typographical differences. As of this commit there is no DocBook remaining in the options documentation. You can play along at home if you want to reproduce this commit: $ NIX_PATH=nixpkgs=flake:nixpkgs/c1bca7fe84c646cfd4ebf3482c0e6317a0b13f22 \ nix shell nixpkgs#coreutils \ -c find . -name '*.nix' \ -exec nix run github:emilazy/nix-doc-munge/0a7190f600027bf7baf6cb7139e4d69ac2f51062 \ {} + [my fork of `nix-doc-munge`]: https://github.com/emilazy/nix-doc-munge
2023-06-22 11:21:32 +00:00
Whether to install documentation distributed in packages' `/share/doc`.
documentation: add module for darwin manual Fixes #72
2019-05-04 13:38:17 +00:00
Usually plain text and/or HTML.
This also includes "doc" outputs.
'';
};
};
config = mkIf cfg.enable {
programs.man.enable = cfg.man.enable;
programs.info.enable = cfg.info.enable;
environment.systemPackages = mkMerge [
(mkIf cfg.man.enable [ manual.manpages ])
(mkIf cfg.doc.enable [ manual.manualHTML helpScript ])
];
system.build.manual = manual;
};
}
Copy permalink