New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Extract NixOS options documentation generation to a function #66328
Conversation
This pull request has been mentioned on Nix community. There might be relevant details there: https://discourse.nixos.org/t/documentation-improvements/3111/42 |
Motivation is to support other repositories containing nixos modules that would like to generate options documentation: - nix-darwin - private repos - arion - ??
1d22558
to
5cfd034
Compare
optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList); | ||
|
||
in rec { | ||
# The NixOS options in JSON format. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could we get an optionsNix
for other Nix-internal use-cases? (to avoid reading the JSON back in)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I plan to add that and asciidoc variation, but I'd like to do that as a separate PR to limit the scope here.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Very nice to have some cleanups! I have very slowly been working on something similar for use in Home Manager. Basically I've been wanting to extract the whole documentation generation framework into a project of its own, I uploaded the latest code I have here: nmd. It contains some cleaned up code for option documentation although I can't recall whether it actually works or not. But it is more general than the one in both NixOS and Home Manager in that, for example, the URL for the module is generated by a given function argument rather than being hard coded in the xsl file. |
@rycee that's really cool :) I'd like to improve this interface further until 19.09 is out, so we can incorporate some of your ideas. |
@domenkozar FWIW I played around a bit more with nmd and now Home Manager uses it to build its documentation: https://github.com/rycee/home-manager/blob/master/doc/default.nix. It's a bit ugly but at least it produces the same output as before. |
We had `./options-to-docbook.xsl` as a dependency for `generated` target but it was moved to a package in NixOS#66328.
We had `./options-to-docbook.xsl` as a dependency for `generated` target but it was moved to a package in NixOS#66328. (cherry picked from commit 81e755f)
Motivation is to support other repositories containing nixos
modules that would like to generate options documentation:
Refs hercules-ci/arion#10