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
|
||||
|
||||
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`, via [ndg](https://github.com/feel-co/ndg))
|
||||
- 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_.
|
||||
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