71 lines
2.4 KiB
Markdown
71 lines
2.4 KiB
Markdown
# 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 **unf**uck 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](https://github.com/feel-co/ndg)) that contains a static site with your module documentation.
|
|
|
|
it works like this:
|
|
```nix
|
|
# 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.
|