diff options
author | Johannes Kirschbauer <hsjobeki@gmail.com> | 2024-03-21 16:07:18 +0100 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-03-21 16:07:18 +0100 |
commit | 9a21db7be899fd0c12be15b690c79acf493feeee (patch) | |
tree | 2b19189f9ff5db95a5f6378a8122993c04623b56 | |
parent | d23f4b140f48376b13feb7ef400aa27f6f6219b9 (diff) |
doc: write improved documentation for nixosOptionsDoc (#295279)
* doc: write improved documentation for nixosOptionsDoc * Apply suggestions from @infinisil Co-authored-by: Silvan Mosberger <github@infinisil.com> * doc: minor fixup --------- Co-authored-by: Silvan Mosberger <github@infinisil.com>
-rw-r--r-- | nixos/lib/make-options-doc/default.nix | 99 |
1 files changed, 87 insertions, 12 deletions
diff --git a/nixos/lib/make-options-doc/default.nix b/nixos/lib/make-options-doc/default.nix index 284934a7608ef..09a4022845e04 100644 --- a/nixos/lib/make-options-doc/default.nix +++ b/nixos/lib/make-options-doc/default.nix @@ -1,20 +1,95 @@ -/* Generate JSON, XML and DocBook documentation for given NixOS options. +/** + Generates documentation for [nix modules](https://nix.dev/tutorials/module-system/module-system.html). - Minimal example: + It uses the declared `options` to generate documentation in various formats. - { pkgs, }: + # Outputs - let - eval = import (pkgs.path + "/nixos/lib/eval-config.nix") { - baseModules = [ - ../module.nix - ]; - modules = []; - }; - in pkgs.nixosOptionsDoc { - options = eval.options; + This function returns an attribute set with the following entries. + + ## optionsCommonMark + + Documentation in CommonMark text format. + + ## optionsJSON + + All options in a JSON format suitable for further automated processing. + + `example.json` + ```json + { + ... + "fileSystems.<name>.options": { + "declarations": ["nixos/modules/tasks/filesystems.nix"], + "default": { + "_type": "literalExpression", + "text": "[\n \"defaults\"\n]" + }, + "description": "Options used to mount the file system.", + "example": { + "_type": "literalExpression", + "text": "[\n \"data=journal\"\n]" + }, + "loc": ["fileSystems", "<name>", "options"], + "readOnly": false, + "type": "non-empty (list of string (with check: non-empty))" + "relatedPackages": "- [`pkgs.tmux`](\n https://search.nixos.org/packages?show=tmux&sort=relevance&query=tmux\n )\n", + }, + ... + } + ``` + + ## optionsDocBook + + deprecated since 23.11 and will be removed in 24.05. + + ## optionsAsciiDoc + + Documentation rendered as AsciiDoc. This is useful for e.g. man pages. + + > Note: NixOS itself uses this ouput to to build the configuration.nix man page" + + ## optionsNix + + All options as a Nix attribute set value, with the same schema as `optionsJSON`. + + # Example + + ## Example: NixOS configuration + + ```nix + let + # Evaluate a NixOS configuration + eval = import (pkgs.path + "/nixos/lib/eval-config.nix") { + # Overriden explicitly here, this would include all modules from NixOS otherwise. + # See: docs of eval-config.nix for more details + baseModules = []; + modules = [ + ./module.nix + ]; + }; + in + pkgs.nixosOptionsDoc { + inherit (eval) options; } + ``` + + ## Example: non-NixOS modules + + `nixosOptionsDoc` can also be used to build documentation for non-NixOS modules. + ```nix + let + eval = lib.evalModules { + modules = [ + ./module.nix + ]; + }; + in + pkgs.nixosOptionsDoc { + inherit (eval) options; + } + ``` */ { pkgs , lib |