From d7fd3cf4a833f3642d11eac335b54ee5d66e4bb0 Mon Sep 17 00:00:00 2001 From: atagen Date: Wed, 30 Jul 2025 16:36:54 +1000 Subject: [PATCH] rewrite readme for new outputs --- RANT.md | 70 +++++++++++++++++++++++++++++++++++++++ README.md | 99 +++++++++++++++++++++++-------------------------------- 2 files changed, 112 insertions(+), 57 deletions(-) create mode 100644 RANT.md diff --git a/RANT.md b/RANT.md new file mode 100644 index 0000000..bc99c34 --- /dev/null +++ b/RANT.md @@ -0,0 +1,70 @@ +# 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. diff --git a/README.md b/README.md index bc99c34..b542402 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,55 @@ # UNF -a painless gateway to nixos module documentation. +`unf` is the simplest possible way to generate documentation for a nix module. -## ever tried to -### generate documentation -#### from a nixos module you've written? +given a few straightforward parameters, its `lib` provides documentation outputs for: +- a full documentation website (`html`) +- commonmark (`md`) +- `json` +- `yaml` +- `toml` +- rudimentary `xml` +- raw `nix` attrs -if you have, you know it sucks. deeply. +here's how it works: -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 +````nix # in your flake +{ + inputs = { + nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; + unf.url = "git+https://git.atagen.co/atagen/unf"; + }; -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 ]; - }; -}; + outputs = { self, nixpkgs, unf }: { + packages.${system}.docs = unf.lib.html { + # a reference to your flake's self, for path replacement + inherit self; + # an instance of nixpkgs, required for evaluating the raw options + pkgs = nixpkgs.legacyPackages.${system}; + # 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 ]; + # any options the user wishes to pass to nixosOptionsDoc + userOpts = { warningsAreErrors = false; }; + }; + }; +} # in your shell $ nix build .#docs -``` -and _that's it_. +```` -enjoy. +and that's it. + +enjoy ! + + +if you are looking for the old readme, it is [here](./RANT.md)