doc/doc-support: Generalize library docs code #305847
Conversation
It was quite small, so the indirection was just going to be annoying.
| if [[ -e "../lib/$baseName.nix" ]]; then | ||
| nixdoc -c "$name" -d "lib.$name: $description" -l ${locationsJSON} -f "$baseName.nix" > "$out/$name.md" | ||
| nixdoc -c "$name" -d "$PREFIXDOT$name: $description" -l ${locationsJSON} -f "$baseName.nix" --prefix "$PREFIX" > "$out/$name.md" |
There was a problem hiding this comment.
This would require nixdoc to support that feature as you already mentioned. I could take care of that in the next couple of days.
| library = pkgs.lib; | ||
| src = ../lib; | ||
| name = "nixpkgs-lib-docs"; | ||
| prefix = "lib"; |
There was a problem hiding this comment.
A am about to change this default in nixdoc. Can you change it to "lib." already here ?
There was a problem hiding this comment.
So more like a string prefix than a path prefix? That's also fine.
There was a problem hiding this comment.
Isn't that what you requested in nix-community/nixdoc#119? Or did I understand it wong?
This now depends on which one gets merged earlier. Ideally, we would merge this PR first nix-community/nixdoc#122 to support empty prefixes with the default prefix="lib.".
The problem is, that if we change the prefix delimiter in the wrong way. The manual will not build because the heading IDs on the manual change.
If we merge this one first, we are in a deadlock. Where we must implement a backwards compatible migration in nixdoc.
There was a problem hiding this comment.
Both solutions are valid, and I don't have a preference.
Requiring the . to be specified on the command line is more of a breaking change, but the implementation is slightly simpler.
|
@infinisil We could merge this one i think. I'd like to extend the docs by pkgs.* functions. Maybe i can work that into nixdoc, by using the semi-stable nix-c-bindings next. No sure how that works out with rust ;) |
|
It looks like it has been "generalized" with default arguments. That's fine. It was just a small refactor anyway. |
|
Ugh, closing feels so harsh? It's fine. |
Description of changes
This refactors
doc/doc-support/lib-function-docs.nixso that it will be usable for other libraries thanlib.Future usages may include:
pkgs.formats(currentlynixos/doc/manual/development/settings-options.section.md)nixos/lib/default.nixlibraryThis PR also anticipates
Things done
nix.conf? (See Nix manual)sandbox = relaxedsandbox = truenix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)Add a 👍 reaction to pull requests you find important.