Using and documenting the module system outside NixOS

viperML commented 1 year ago

NixOS, home-manager, nix-darwin (and some others) use the NixOS module system. As it can be used outside NixOS, I'll refer to it as the module system.

Instatiating `eval-modules`

Creating your own module system evaluation begins as a simple task. All you need is lib.evalModules and supply it your module list. I believe this is not documented anywhere, but it is easy enough to put together.

Documenting your own module system

I believe a step forward towards having better documentation for the nix ecosystem is providing the users with tools for documenting their work. Unfortunately this is not the case for eval-modules. The tools to document the module system, are not documented anywhere! (or at least I didn't find any doc)

By digging the source code, NixOS uses pkgs.nixosOptionsDoc which can be used to generate markdown or asciidoc, or other intermediate representation formats like JSON. It would be nicer to have some pre-made solution to output some static webpage ready to publish on GitHub pages or similar.

And to this day, I don't know how I can generate man-pages out of a module system implementation.

Example

Last month I created wrapper-manager, which uses the module system. I had to go through reading source code of the nixos and HM manuals to put together a solution. Even after that, I am left with some raw markdown that I have to wire up into hugo, with this result: https://viperml.github.io/wrapper-manager/docs/module

Proposal

Document how to use eval-modules for a custom module implementation.
Provide tools for easily documenting a eval-modules result

Add :+1: to issues you find important.

NobbZ commented 1 year ago

In general the "module system" (official name according to one of its creators (can't find the discourse thread for a citation)) has its documentation spread across the NixOS and the nixpkgs manual.

From what I get, the former has handwritten documentation about how it works in the NixOS context, while the nixpkgs manual is just a collection of autogenerated function documentation from the <nixpkgs/lib> folder.

Eg. lib.evalModules

Anyway, its sparse and "reference" documentation, in both manuals. A more hands on style of documentation would be appreciated.

fricklerhandwerk commented 1 year ago

nixos-discourse commented 1 year ago

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/try-to-understand-nix-function-paramters-and-attributes/32637/2

hugosenari commented 10 months ago

Provide tools for easily documenting a eval-modules result

https://git.sr.ht/~rycee/nmd should help, it uses same tools of NixOS to creates man files.

I created a module around it.

My approach is: docs = nmd.buildModulesDocs; to create a docs.optionsDocs, that I convert to whatever a need, ie:

for json, yaml, toml: I convert to json and pass yj command (there is nixpkgs converters but yj has lower closure size)
for MD is tricky
- pass to Root MD converter that calls
- Recursive MD converter

NixOS / nixpkgs