mirror of
https://git.atagen.co/atagen/unf.git
synced 2025-12-26 11:44:59 +08:00
rewrite readme for new outputs
This commit is contained in:
atagen
parent
480737fc84
commit
29dbb12ea5
2 changed files with 111 additions and 58 deletions
70
RANT.md
Normal file
70
RANT.md
Normal file
|
|
@ -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.
|
||||||
99
README.md
99
README.md
|
|
@ -1,70 +1,53 @@
|
||||||
# UNF
|
# UNF
|
||||||
|
|
||||||
a painless gateway to nixos module documentation.
|
`unf` is the simplest possible way to generate documentation for a nix module.
|
||||||
|
|
||||||
## ever tried to
|
given a few straightforward parameters, its `lib` provides documentation outputs for:
|
||||||
### generate documentation
|
- a full documentation website (`html`, via [ndg](https://github.com/feel-co/ndg))
|
||||||
#### from a nixos module you've written?
|
- 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.
|
````nix
|
||||||
|
|
||||||
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
|
# in your flake
|
||||||
|
{
|
||||||
|
inputs = {
|
||||||
|
nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
|
||||||
|
unf.url = "git+https://git.atagen.co/atagen/unf";
|
||||||
|
};
|
||||||
|
|
||||||
inputs = {
|
outputs = { self, nixpkgs, unf }: {
|
||||||
unf.url = "git+https://git.atagen.co/atagen/unf";
|
packages.${system}.docs = unf.lib.html {
|
||||||
};
|
# a reference to your flake's self, for path replacement
|
||||||
|
inherit self;
|
||||||
outputs = {
|
# an instance of nixpkgs, required for evaluating the raw options
|
||||||
packages.${system}.docs = pkgs.callPackage inputs.unf.lib.pak-chooie {
|
pkgs = nixpkgs.legacyPackages.${system};
|
||||||
# a reference to your flake's self, for path replacement
|
# the name of your project, for page title etc
|
||||||
inherit self;
|
projectName = "unf";
|
||||||
# the name of your project, for page title etc
|
# the intended base path for files referred to by your docs, ie. your public repo
|
||||||
projectName = "unf";
|
newPath = "https://git.atagen.co/atagen/unf";
|
||||||
# the intended base path for files referred to by your docs, ie. your public repo
|
# any specialArgs you want in the module system while evaluating your options
|
||||||
newPath = "https://git.atagen.co/atagen/unf";
|
specialArgs = { goodDx = true; };
|
||||||
# any specialArgs you want in the module system while evaluating your options
|
# the modules you wish to document
|
||||||
specialArgs = { goodDx = true; };
|
modules = [ ./nix/interface.nix ];
|
||||||
# the modules you wish to document
|
# any options the user wishes to pass to nixosOptionsDoc
|
||||||
modules = [ ./nix/interface.nix ];
|
userOpts = { warningsAreErrors = false; };
|
||||||
};
|
};
|
||||||
};
|
};
|
||||||
|
}
|
||||||
|
|
||||||
# in your shell
|
# in your shell
|
||||||
|
|
||||||
$ nix build .#docs
|
$ nix build .#docs
|
||||||
|
````
|
||||||
|
|
||||||
```
|
and that's it.
|
||||||
and _that's it_.
|
|
||||||
|
|
||||||
enjoy.
|
enjoy !
|
||||||
|
|
||||||
|
|
||||||
|
<sub>if you are looking for the old readme, it is [here](./RANT.md)</sub>
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue