nix-community.nixvim/docs/mdbook/default.nix

{
  pkgs,
  lib,
  modules,
  helpers,
  nixosOptionsDoc,
  transformOptions,
  hmOptions,
}:
with lib;
let
  options = lib.evalModules {
    inherit modules;
    specialArgs = {
      inherit pkgs lib helpers;
    };
  };

  inherit (options.config.meta) nixvimInfo;

  mkMDDoc =
    options:
    (nixosOptionsDoc {
      inherit options transformOptions;
      warningsAreErrors = false;
    }).optionsCommonMark;

  removeUnwanted =
    attrs:
    builtins.removeAttrs attrs [
      "_module"
      "_freeformOptions"
      "warnings"
      "assertions"
      "content"
    ];

  removeWhitespace = builtins.replaceStrings [ " " ] [ "" ];

  getSubOptions = opts: path: removeUnwanted (opts.type.getSubOptions path);

  isVisible =
    opts:
    if isOption opts then
      attrByPath [ "visible" ] true opts
    else if opts.isOption then
      attrByPath [
        "index"
        "options"
        "visible"
      ] true opts
    else
      let
        filterFunc = filterAttrs (_: v: if isAttrs v then isVisible v else true);

        hasEmptyIndex = (filterFunc opts.index.options) == { };
        hasEmptyComponents = (filterFunc opts.components) == { };
      in
      !hasEmptyIndex || !hasEmptyComponents;

  wrapModule = path: opts: isOpt: rec {
    index = {
      options =
        if isOpt then
          opts
        else
          filterAttrs (_: component: component.isOption && (isVisible component)) opts;
      path = removeWhitespace (concatStringsSep "/" path);
      moduleDoc =
        if builtins.length path >= 2 && lib.hasAttrByPath path nixvimInfo then
          let
            info = lib.getAttrFromPath path nixvimInfo;
            maintainers = lib.unique (options.config.meta.maintainers.${info.file} or [ ]);
            maintainersNames = builtins.map (m: m.name) maintainers;
          in
          "# ${lib.last path}\n\n"
          + (lib.optionalString (info.description != null) "${info.description}\n\n")
          + (lib.optionalString (info.url != null) "**Url:** [${info.url}](${info.url})\n\n")
          + (lib.optionalString (
            builtins.length maintainers > 0
          ) "**Maintainers:** ${lib.concatStringsSep ", " maintainersNames}\n\n")
        else
          null;
    };

    components =
      if isOpt then
        { }
      else
        filterAttrs (_: component: !component.isOption && (isVisible component)) opts;

    hasComponents = components != { };

    isOption = isOpt;
  };

  processModulesRec =
    modules:
    let
      recurse =
        path: mods:
        let
          g =
            name: opts:
            if !isOption opts then
              wrapModule (path ++ [ name ]) (recurse (path ++ [ name ]) opts) false
            else
              let
                subOpts = getSubOptions opts (path ++ [ name ]);
              in
              if subOpts != { } then
                wrapModule (path ++ [ name ]) (
                  (recurse (path ++ [ name ]) subOpts)
                  // {
                    # This is necessary to include the submodule option's definition in the docs (description, type, etc.)
                    # For instance, this helps submodules like "autoCmd" to include their base definitions and examples in the docs
                    # Though there might be a better, less "hacky" solution than this.
                    ${name} = recursiveUpdate opts {
                      isOption = true;
                      type.getSubOptions = _: _: { }; # Used to exclude suboptions from the submodule definition itself
                    };
                  }
                ) false
              else
                wrapModule (path ++ [ name ]) opts true;
        in
        mapAttrs g mods;
    in
    foldlAttrs (
      acc: name: opts:
      let
        group = if !opts.hasComponents then "Neovim Options" else "none";

        last =
          acc.${group} or {
            index = {
              options = { };
              path = removeWhitespace "${group}";
              moduleDoc = null;
            };
            components = { };
            isGroup = true;
            hasComponents = false;
          };

        isOpt = !opts.hasComponents && (isOption opts.index.options);
      in
      acc
      // {
        ${group} = recursiveUpdate last {
          index.options = optionalAttrs isOpt { ${name} = opts.index.options; };

          components = optionalAttrs (!isOpt) {
            ${name} = recursiveUpdate opts {
              index.path = removeWhitespace (
                concatStringsSep "/" ((optional (group != "none") group) ++ [ opts.index.path ])
              );
              hasComponents = true;
            };
          };

          hasComponents = last.components != { };
        };
      }
    ) { } (recurse [ ] modules);

  mapModulesToString =
    f: modules:
    let
      recurse =
        mods:
        let
          g =
            name: opts:
            if (opts ? "isGroup") then
              if name != "none" then (f name opts) + ("\n" + recurse opts.components) else recurse opts.components
            else if opts.hasComponents then
              (f name opts) + ("\n" + recurse opts.components)
            else
              f name opts;
        in
        concatStringsSep "\n" (mapAttrsToList g mods);
    in
    recurse modules;

  docs = rec {
    modules = processModulesRec (removeUnwanted options.options);
    commands = mapModulesToString (
      name: opts:
      let
        isBranch = if (hasSuffix "index" opts.index.path) then true else opts.hasComponents;
        path = if isBranch then "${opts.index.path}/index.md" else "${opts.index.path}.md";
      in
      (optionalString isBranch "mkdir -p ${opts.index.path}\n")
      + (
        if opts.index.moduleDoc == null then
          "cp ${mkMDDoc opts.index.options} ${path}"
        else
          # Including moduleDoc's text directly will result in bash interpreting special chars,
          # write it to the nix store and `cat` the file instead.
          ''
            {
            cat ${pkgs.writeText "module-doc" opts.index.moduleDoc}
            cat ${mkMDDoc opts.index.options}
            } > ${path}
          ''
      )
    ) modules;
  };

  mdbook = {
    nixvimOptions = mapModulesToString (
      name: opts:
      let
        isBranch = if name == "index" then true else opts.hasComponents && opts.index.options != { };

        path =
          if isBranch then
            "${opts.index.path}/index.md"
          else if !opts.hasComponents then
            "${opts.index.path}.md"
          else
            "";

        indentLevel = with builtins; length (filter isString (split "/" opts.index.path)) - 1;

        padding = concatStrings (builtins.genList (_: "\t") indentLevel);
      in
      "${padding}- [${name}](${path})"
    ) docs.modules;
  };

  prepareMD = ''
    # Copy inputs into the build directory
    cp -r --no-preserve=all $inputs/* ./
    cp ${../../CONTRIBUTING.md} ./CONTRIBUTING.md
    cp -r ${../user-guide} ./user-guide
    cp -r ${../modules} ./modules

    # Copy the generated MD docs into the build directory
    # Using pkgs.writeShellScript helps to avoid the "bash: argument list too long" error
    bash -e ${pkgs.writeShellScript "copy_docs" docs.commands}

    # Prepare SUMMARY.md for mdBook
    # Using pkgs.writeText helps to avoid the same error as above
    substituteInPlace ./SUMMARY.md \
      --replace-fail "@NIXVIM_OPTIONS@" "$(cat ${pkgs.writeText "nixvim-options-summary.md" mdbook.nixvimOptions})"

    substituteInPlace ./modules/hm.md \
      --replace-fail "@HM_OPTIONS@" "$(cat ${mkMDDoc hmOptions})"
  '';
in
pkgs.stdenv.mkDerivation {
  name = "nixvim-docs";

  phases = [ "buildPhase" ];

  buildInputs = [ pkgs.mdbook ];
  inputs = sourceFilesBySuffices ./. [
    ".md"
    ".toml"
    ".js"
  ];

  buildPhase = ''
    dest=$out/share/doc
    mkdir -p $dest
    ${prepareMD}
    mdbook build
    cp -r ./book/* $dest
  '';
}