make-options-doc: expose Nix set and add asciidoc variant #66436
Conversation
|
What does this do? |
|
Allows you to render options via Nix structures instead of using JSON. |
domenkozar
changed the title
domenkozar
force-pushed
the
nixos-options-doc-nix
branch
from
80a65d7
to
6cf861c
Compare
|
Given that you have { pkgs }:
let
eval = import (pkgs.path + "/nixos/lib/eval-config.nix") {
baseModules = [
../module.nix
];
modules = [];
};
options = pkgs.nixosOptionsDoc {
options = eval.options;
};
in {
options = pkgs.writeText "my-nixos-options" ''
= NixOS Options
${options.optionsAsciiDoc}
'' ;
}I'll post the result example :) |
| singleAsciiDoc = name: value: '' | ||
| == ${name} | ||
|
|
||
| ${value.description} |
There was a problem hiding this comment.
unfortunately, options docs assume Docbook in many places. Things like </para><para> and <literal> are pretty common in descriptions. So it would be more complicated than this.
There was a problem hiding this comment.
We'll need to process those, but this is a good start for options outside of nixos (I don't expect asciidoc to be used in nixos).
There was a problem hiding this comment.
okay, so it was not clear that this is not a start if asciidocization, but just a helper function for modules written outside of Nixpkgs. And nobody should really try to use this against default Nixos modules.
And really, only optionsNix has to be exposed here. Everything else can be built on top of outside of Nixpkgs. This asciidoc variant is more of an example, but a useful example.
There was a problem hiding this comment.
It is a start, but it's only really useful outside of nixpkgs and partially inside nixpkgs.
Everything else can be built on top of outside of Nixpkgs.
Nixpkgs is supposed to be the central Nix packaging repo and since Hydra doesn't allow IFD, there's little choice here. Flakes will make it easier, but as of today in order to distribute reusable Nix code, nixpkgs is the only sane place.
Think of it this way: if we never challenge docbook tooling, we'll be stuck with it forever. Some might like this, but why kill the efforts of those that don't?
No description provided.