modules/docs: construct docs from docs.* options

Introduce various `docs.*` options where doc pages, menu entries, etc
can be defined.

The options themselves are responsible for rendering this to markdown
and HTML.

Author: MattSturgeon

modules/default.nix

@@ -23,4 +23,9 @@
     ./performance.nix
     ./plugins.nix
   ];
+
+  docs.options.options = {
+    enable = true;
+    optionScopes = [ ];
+  };
 }

modules/docs/_util.nix

@@ -0,0 +1,166 @@
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+let
+  inherit (config.docs.menu)
+    sections
+    ;
+
+  transformOption =
+    let
+      root = builtins.toString ../../.;
+      mkGitHubDeclaration = user: repo: branch: subpath: {
+        url = "https://github.com/${user}/${repo}/blob/${branch}/${subpath}";
+        name = "<${repo}/${subpath}>";
+      };
+      transformDeclaration =
+        decl:
+        if lib.hasPrefix root (builtins.toString decl) then
+          mkGitHubDeclaration "nix-community" "nixvim" "main" (
+            lib.removePrefix "/" (lib.strings.removePrefix root (builtins.toString decl))
+          )
+        else if decl == "lib/modules.nix" then
+          mkGitHubDeclaration "NixOS" "nixpkgs" "master" decl
+        else
+          decl;
+    in
+    opt: opt // { declarations = builtins.map transformDeclaration opt.declarations; };
+
+  docsPageModule =
+    { name, config, ... }:
+    {
+      options = {
+        enable = lib.mkOption {
+          type = lib.types.bool;
+          description = "Whether to enable this page/menu item.";
+          default = true;
+          example = false;
+        };
+        target = lib.mkOption {
+          type = lib.types.str;
+          description = ''
+            The target filepath, relative to the root of the docs.
+          '';
+          default = lib.optionalString (name != "") (name + "/") + "index.md";
+          defaultText = lib.literalMD ''
+            `<name>` joined with `"index.md"`. Separated by `"/"` if `<name>` is non-empty.
+          '';
+        };
+        source = lib.mkOption {
+          type = with lib.types; nullOr path;
+          description = ''
+            Markdown page. Set to null to create a menu entry without a corresponding file.
+          '';
+        };
+        menu.location = lib.mkOption {
+          type = with lib.types; listOf str;
+          description = ''
+            A location path that represents the page's position in the menu tree.
+
+            The text displayed in the menu is derived from this value,
+            after the location of any parent nodes in the tree is removed.
+
+            For example, if this page has the location `[ "foo" "bar" ]`
+            and there is another page with the location `[ "foo" ]`,
+            then the menu will render as:
+            ```markdown
+            - foo
+              - bar
+            ```
+
+            However if there was no other page with the `[ "foo" ]` location,
+            the menu would instead render as:
+            ```markdown
+            - foo.bar
+            ```
+          '';
+          default =
+            let
+              list = lib.splitString "/" config.target;
+              last = lib.last list;
+              rest = lib.dropEnd 1 list;
+            in
+            if last == "index.md" then
+              rest
+            else if lib.hasSuffix ".md" last then
+              rest ++ [ (lib.removeSuffix ".md" last) ]
+            else
+              list;
+          defaultText = lib.literalMD ''
+            `target`, split by `"/"`, with any trailing `"index.md` or `".md"` suffixes removed.
+          '';
+        };
+        menu.section = lib.mkOption {
+          type = lib.types.enum (builtins.attrNames sections);
+          description = ''
+            Determines the menu section.
+
+            Must be a section defined in `docs.menu.sections`.
+          '';
+        };
+      };
+    };
+in
+{
+  options.docs._utils = lib.mkOption {
+    type = with lib.types; lazyAttrsOf raw;
+    description = "internal utils, modules, functions, etc";
+    default = { };
+    internal = true;
+    visible = false;
+  };
+
+  config.docs._utils = {
+    # A liberal type that permits any superset of docsPageModule
+    docsPageLiberalType = lib.types.submodule [
+      { _module.check = false; }
+      docsPageModule
+    ];
+
+    /**
+      Uses `lib.optionAttrSetToDocList` to produce a list of docs-options.
+
+      A doc-option has the following attrs, as expected by `nixos-render-docs`:
+
+      ```
+      {
+        loc,
+        name, # rendered with `showOption loc`
+        description,
+        declarations,
+        internal,
+        visible, # normalised to a boolean
+        readOnly,
+        type, # normalised to `type.description`
+        default,? # rendered with `lib.options.renderOptionValue`
+        example,? # rendered with `lib.options.renderOptionValue`
+        relatedPackages,?
+      }
+      ```
+
+      Additionally, sub-options are recursively flattened into the list,
+      unless `visible == "shallow"` or `visible == false`.
+
+      This function extends `lib.optionAttrSetToDocList` by also filtering out
+      invisible and internal options, and by applying Nixvim's `transformOption`
+      function.
+
+      The implementation is based on `pkgs.nixosOptionsDoc`:
+      https://github.com/NixOS/nixpkgs/blob/e2078ef3/nixos/lib/make-options-doc/default.nix#L117-L126
+    */
+    mkOptionList = lib.flip lib.pipe [
+      (lib.flip builtins.removeAttrs [ "_module" ])
+      lib.optionAttrSetToDocList
+      (builtins.map transformOption)
+      (builtins.filter (opt: opt.visible && !opt.internal))
+      # TODO: consider supporting `relatedPackages`
+      # See https://github.com/NixOS/nixpkgs/blob/61235d44/lib/options.nix#L103-L104
+      # and https://github.com/NixOS/nixpkgs/blob/61235d44/nixos/lib/make-options-doc/default.nix#L128-L165
+    ];
+
+    inherit docsPageModule;
+  };
+}

modules/docs/all.nix

@@ -0,0 +1,49 @@
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+let
+  inherit (config.docs._utils)
+    docsPageLiberalType
+    ;
+in
+{
+  options.docs = {
+    _allInputs = lib.mkOption {
+      type = with lib.types; listOf str;
+      description = "`docs.*` option names that should be included in `docs.all`.";
+      defaultText = config.docs._allInputs;
+      default = [ ];
+      internal = true;
+      visible = false;
+    };
+    all = lib.mkOption {
+      type = with lib.types; listOf docsPageLiberalType;
+      description = ''
+        All enabled doc pages defined in:
+        ${lib.concatMapStringsSep "\n" (name: "- `docs.${name}`") config.docs._allInputs}.
+      '';
+      visible = "shallow";
+      readOnly = true;
+    };
+    src = lib.mkOption {
+      type = lib.types.package;
+      description = "All source files for the docs.";
+      readOnly = true;
+    };
+  };
+
+  config.docs = {
+    # Copy all pages from options listed in _allInputs
+    all = builtins.filter (page: page.enable or true) (
+      builtins.concatMap (name: builtins.attrValues config.docs.${name}) config.docs._allInputs
+    );
+
+    # A directory with all the files in it
+    src = pkgs.callPackage ./src.nix {
+      pages = builtins.filter (page: page.source or null != null) config.docs.all;
+    };
+  };
+}

modules/docs/default.nix

@@ -5,4 +5,24 @@
     default = true;
     description = "Install the man pages for NixVim options.";
   };
+
+  imports = [
+    ./_util.nix
+    ./all.nix
+    ./files.nix
+    ./mdbook
+    ./menu
+    ./options.nix
+    ./platforms.nix
+  ];
+
+  config.docs.options = {
+    docs = {
+      menu.location = [ "docs" ];
+      optionScopes = [ "docs" ];
+      description = ''
+        Internal options used to construct these docs.
+      '';
+    };
+  };
 }

modules/docs/files.nix

@@ -0,0 +1,89 @@
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+let
+  inherit (config.docs._utils)
+    docsPageModule
+    ;
+
+  docsPageType = lib.types.submodule (
+    {
+      name,
+      config,
+      options,
+      ...
+    }:
+    let
+      derivationName = builtins.replaceStrings [ "/" ] [ "-" ] name;
+    in
+    {
+      imports = [
+        docsPageModule
+      ];
+      options.text = lib.mkOption {
+        type = with lib.types; nullOr lines;
+        default = null;
+        description = "Text of the file.";
+      };
+      config.source = lib.mkIf (config.text != null) (
+        lib.mkDerivedConfig options.text (builtins.toFile derivationName)
+      );
+    }
+  );
+
+  user-guide = ../../docs/user-guide;
+
+  sourceTransformers = {
+    config-examples =
+      template:
+      pkgs.callPackage ./user-configs.nix {
+        inherit template;
+      };
+  };
+in
+{
+  options.docs = {
+    files = lib.mkOption {
+      type = with lib.types; lazyAttrsOf docsPageType;
+      description = ''
+        A set of pages to include in the docs.
+      '';
+      default = { };
+    };
+  };
+
+  config.docs = {
+    files =
+      # TODO: contributing file
+      {
+        "" = {
+          menu.section = "header";
+          menu.location = [ "Home" ];
+          source = pkgs.callPackage ./readme.nix {
+            # TODO: get `availableVersions` and `baseHref` from module options
+          };
+        };
+      }
+      // lib.concatMapAttrs (
+        name: type:
+        let
+          title = lib.removeSuffix ".md" name;
+          transformer = sourceTransformers.${title} or lib.id;
+        in
+        lib.optionalAttrs (type == "regular") {
+          "user-guide/${title}" = {
+            menu.section = "user-guide";
+            # TODO: define user-facing titles to show in the menu...
+            menu.location = [ title ];
+            source = transformer "${user-guide}/${name}";
+          };
+        }
+      ) (builtins.readDir user-guide);
+
+    # Register for inclusion in `all`
+    _allInputs = [ "files" ];
+  };
+}

modules/docs/mdbook/default.nix

@@ -0,0 +1,50 @@
+{
+  lib,
+  config,
+  pkgs,
+  ...
+}:
+let
+  settingsFormat = pkgs.formats.toml { };
+  defaultSettings = {
+    book = {
+      language = "en";
+      multilingual = false;
+      title = "nixvim docs";
+    };
+    build.create-missing = false;
+    output.html.site-url = "/";
+    output.html.fold = {
+      enable = true;
+      level = 0;
+    };
+    preprocessor.alerts = { };
+  };
+in
+{
+  options.docs.html = {
+    site = lib.mkOption {
+      type = lib.types.package;
+      description = "HTML docs rendered by mdbook.";
+      readOnly = true;
+    };
+    settings = lib.mkOption {
+      inherit (settingsFormat) type;
+      description = ''
+        Freeform settings written to `book.toml`.
+
+        See MDBook's [Configuration](https://rust-lang.github.io/mdBook/format/configuration/index.html) docs.
+      '';
+      defaultText = defaultSettings;
+    };
+  };
+  config.docs.html = {
+    site = pkgs.callPackage ./package.nix {
+      inherit (config.docs) src;
+      inherit (config.docs.html) settings;
+      menu = config.docs.menu.src;
+      writeTOML = settingsFormat.generate;
+    };
+    settings = defaultSettings;
+  };
+}