nix-community
Documentation for the disko configuration format
Currently for a user to learn and use disko, they have to look through various examples of different setups, since there's no central documentation of the format. And for something as complex as filesystem setup, this is often not enough for users to infer where can each option be set, what they mean and how to customize them. A quick glance shows that tens of issues are directly related to the configuration being written wrong or misunderstood.
To improve user friendliness and reduce the effort of explaining the format, would you like to create a specification document for the configuration format?
Just found that it is explained here: https://github.com/nix-community/disko/blob/master/docs/reference.md
It would be nice if we could fix this issue. I'm wondering how option documentation is usually generated, I haven't looked into that yet.
@tim-elmer you're right. I actually merged a change recently that should enable us to work on this without hitting the recursion issue: #874
I'm wondering how option documentation is usually generated, I haven't looked into that yet.
It was possible to come up with these examples.
nix-options-doc, mmdoc, Nix Reference Manual
While mmdoc looks opinionated, a less sophisticated approach is followed by nmd, in use at home-manager and skarabox, for example.
Examples
Skarabox shows us a medium-scale build infrastructure, which is less complex in comparison to home-manager.
- skarabox/template/README.md at main · ibizaman/skarabox
- skarabox/docs/normal-operations.md at main · ibizaman/skarabox
- skarabox/docs/default.nix at main · ibizaman/skarabox
Unfortunately I wasn't able to discern where nixos-render-docs in skarabox/docs/default.nix comes from nor what it does.
- https://github.com/ibizaman/skarabox/blob/7470c94f01392a208ebffc8cefdf50602b3eff64/docs/default.nix#L9
- https://github.com/ibizaman/skarabox/blob/7470c94f01392a208ebffc8cefdf50602b3eff64/docs/default.nix#L157-L168
If anybody could enlighten me about that, please do.
There's another example for mdBook at quadlet-nix. ¹ ²
@almereyda looking back at the code I was confused too but it's simply a package. In my Skarabox project, a lot is hardcoded. I recently refactored my other project SelfHostBlocks (both use the same underlying code to generate the documentation) to be more generic. And it's usage.
I'd love to split this out in its own repo if you find it useful. It could even be a project in nix-community?
I see the nmd/nixos-render-docs output clearly as the most simple, straightforward way to produce Nix documentation that I've seen. If that'd be available easily as a reference way of doing (a first take at) Nix module/flake documentation (without search, navigation, …), the better.