Generating documentation for templates

[osemenovsky]

Hello, I'm experimenting with nixidy lately and I created a template for one of our components. Unfortunately I can't share the template, but it is valid and works as intended, however when I added the template to the doc-generating code I've been working on it doesn't appear in generated docs. I figure it's because templates have a structure unusual to that of a regular NixOS module considering docs for other modules I created are generated correctly. I know it's a skill issue and I'm sure I'll figure it out in time, but maybe someone could point me in the correct direction.

Here's the code I'm using to generate docs (i've anonymized it, but the structure is pretty much the same down to the number of modules.)

{
  lib,
  runCommand,
  nixosOptionsDoc,
  nixidy,
  ...
}: let
  options = (lib.evalModules {
    modules = [
      { config._module.check = false; }
      ../modules/example/helm.nix
      ../modules/example/apps/example-app.nix
      ../modules/example/templates/example-component-template.nix
    ];
  }).options;
  optionsDoc = nixosOptionsDoc {
    options = (builtins.removeAttrs options ["_module"]);
  };
in optionsDoc.optionsCommonMark

[arnarg]

Hi @osemenovsky! Thanks for your question.

So are you generating documentation for all your defined module options, similar to nixidy's options reference but just for yours, and you want your defined templates and their avilable options to be included?

[osemenovsky]

Hey @arnarg! Thanks for a quick reply! I seem to have already figured out a solution and I will post it here after cleaning it up a bit!
And provide clarifications as well

[osemenovsky]

So yes, I'm trying to generate documentation for all of the custom modules I have defined, currently in markdown format though the endgame is to be able to build a NuschtOS search site, but that's later.

My current solution is as follows:

{
  lib,
  runCommand,
  nixosOptionsDoc,
  pkgs,
  ...
}@inputs: let
  modules = [
    ../modules/example/helm.nix
    ../modules/example/apps/app-1.nix
  ];
  templates = [
    ../modules/example/templates/component-template-1.nix
    ../modules/example/templates/component-template-2.nix
  ];
  chainLists = builtins.foldl' (acc: elem: acc ++ elem) [];
  adaptTemplateModule = path: (builtins.map 
    (template: {
      options.templates.${template.name} = template.value.options;
    })
    (lib.attrsToList (import path inputs).templates)
  );
  adaptTemplateModules = modules: (chainLists
    (builtins.map adaptTemplateModule modules));
  optionsDoc = nixosOptionsDoc {
    options = (builtins.removeAttrs (lib.evalModules {
      modules = 
        [{ config._module.check = false; }]
        ++ modules
        ++ adaptTemplateModules templates;
    }).options ["_module"]);
  };
in optionsDoc.optionsCommonMark

This way I'm able to generate markdown file including options for all the templates, however there's a few issues:

Path

Instead templates.example-template.<name>.option-name the path it generates is templates.example-template.option-name,
which is kind of a small issue, but still annoying. I think wrapping it in lib.types.listOf might fix that.

Module path

Since the "modules" are bogus modules, they don't have a path. I imagine it can be fix with _module attribute, but I'm yet to test
this assumption. The larger problem that I get is that paths for regular modules are pointing to nix store instead of the relative path in repository, but that's kinda off-topic. Would be happy to hear any suggestions either way though

[arnarg]

Can you try to change the adaptTemplateModule like this:

adaptTemplateModule = path: (builtins.map 
 (template: {
   _file = path;
   options.templates.${template.name} = lib.mkOption {
     type = lib.types.attrsOf (lib.types.submodule {
       options = template.value.options;
     });
   };
 })
 (lib.attrsToList (import path inputs).templates)
);

I have not tried to run this so some adjustments might be needed.

[osemenovsky]

Huge thanks! It worked exactly as expected! It gave me error about the option description though. I tried adding one to the template itself, but unsurprisingly it doesn't allow for extra fields so i settled on generating a basic description from template name for now.

The only thing that's left is to figure out how to point the paths in the generated markdown file to the repository it's in instead of nix store.

Currently the code looks like this:

{
  lib,
  runCommand,
  nixosOptionsDoc,
  pkgs,
  ...
}@inputs: let
  modules = [
    ../modules/example/helm.nix
    ../modules/example/apps/app-1.nix
  ];
  templates = [
    ../modules/example/templates/component-template-1.nix
    ../modules/example/templates/component-template-2.nix
  ];
  chainLists = builtins.foldl' (acc: elem: acc ++ elem) [];
  adaptTemplateModule = path: (builtins.map 
    (template: {
      _file = path;
      options.templates.${template.name} = with lib; mkOption {
        description = "A template for ${template.name}";
        type = types.attrsOf (types.submodule {
          options = template.value.options;
        });
      };
    })
    (lib.attrsToList (import path inputs).templates)
  );
  adaptTemplateModules = modules: (chainLists
    (builtins.map adaptTemplateModule modules));
  optionsDoc = nixosOptionsDoc {
    options = (builtins.removeAttrs (lib.evalModules {
      modules = 
        [{ config._module.check = false; }]
        ++ modules
        ++ adaptTemplateModules templates;
    }).options ["_module"]);
  };
in optionsDoc.optionsCommonMark

[arnarg]

The only thing that's left is to figure out how to point the paths in the generated markdown file to the repository it's in instead of nix store.

In the nixidy docs I do the following:

1. Get the store path of the repository root (nixidyPath = toString ./..;).
2. Use nixosOptionsDoc's transformOptions and prefix match declaration paths and replace them with URLs.

See: https://github.com/arnarg/nixidy/blob/main/docs/build-options-doc.nix#L197