Unverified Commit 9a21db7b authored by Johannes Kirschbauer's avatar Johannes Kirschbauer Committed by GitHub
Browse files

doc: write improved documentation for nixosOptionsDoc (#295279)



* doc: write improved documentation for nixosOptionsDoc

* Apply suggestions from @infinisil

Co-authored-by: default avatarSilvan Mosberger <github@infinisil.com>

* doc: minor fixup

---------

Co-authored-by: default avatarSilvan Mosberger <github@infinisil.com>
parent d23f4b14
Loading
Loading
Loading
Loading
+87 −12
Original line number Diff line number Diff line
/* Generate JSON, XML and DocBook documentation for given NixOS options.
/**
  Generates documentation for [nix modules](https://nix.dev/tutorials/module-system/module-system.html).

  It uses the declared `options` to generate documentation in various formats.

  # Outputs

  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

   Minimal example:
  All options as a Nix attribute set value, with the same schema as `optionsJSON`.

    { pkgs,  }:
  # Example

  ## Example: NixOS configuration

  ```nix
  let
    # Evaluate a NixOS configuration
    eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
        baseModules = [
          ../module.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
      ];
        modules = [];
    };
    in pkgs.nixosOptionsDoc {
      options = eval.options;
  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