UNF

a painless gateway to nixos module documentation.

ever tried to

generate documentation

from a nixos module you've written?

if you have, you know it sucks. deeply.

sure, more recent tooling fixes cosmetics and end-user experience issues, but does nothing to ease the lives of developers.

instead, they must submit to the perilous traditions of retooling a gargantuan chunk of hellcode wrested from the bowels of nixpkgs itself - all to filter a few store paths, clean up references, and preserve basic semantics in their own documentation.

the unflinchingly cruel authors of these modern nix documentation tools refuse to reconcile the mistakes of the past.
rather than provide a straightforward interface or set of sane defaults, they opt to watch developer after innocent developer attempt to roll this boulder of archaic rot up a hill, flying blind with both feet blown off.

screw 'em, right? they had it coming -
for committing the unforgivable sin of trying to do useful work in the nixos ecosystem.

HOW LONG WILL THIS ABOMINABLE TORTURE PERSIST ???

what if we had a way to simply unfuck this situation ?

what if we could call a package with a straightforward interface that conveys all the information we intend, and have clean, tight docs - robust, searchable, aesthetic, full of tingling erotic energy - simply generated for us on the spot ?

wonder no more.

suffer no more.

PAK-CHOOIE

the only function exposed by unf is lib.pak-chooie.

it produces a package (using ndg) that contains a static site with your module documentation.

it works like this:

# in your flake

inputs = {
  unf.url = "git+https://git.atagen.co/atagen/unf";	
};

outputs = {
  packages.${system}.docs = pkgs.callPackage inputs.unf.lib.pak-chooie {
    # a reference to your flake's self, for path replacement
    inherit self;
    # the name of your project, for page title etc
    projectName = "unf";    
    # the intended base path for files referred to by your docs, ie. your public repo
    newPath = "https://git.atagen.co/atagen/unf";  
    # any specialArgs you want in the module system while evaluating your options
    specialArgs = { goodDx = true; };  
    # the modules you wish to document
    modules = [ ./nix/interface.nix ]; 
  };
};

# in your shell

$ nix build .#docs

and that's it.

enjoy.