Skip to content
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

Merged
merged 1 commit into from Aug 10, 2019

Conversation

domenkozar
Copy link
Member

Motivation is to support other repositories containing nixos
modules that would like to generate options documentation:

  • nix-darwin
  • private repos
  • arion
  • ??

Refs hercules-ci/arion#10

@nixos-discourse
Copy link

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
- ??
optionsXML = builtins.toFile "options.xml" (builtins.toXML optionsList);

in rec {
# The NixOS options in JSON format.
Copy link
Member

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)

Copy link
Member Author

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rycee
Copy link
Member

rycee commented Aug 8, 2019

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.

@domenkozar
Copy link
Member Author

@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 domenkozar merged commit 5ce8864 into NixOS:master Aug 10, 2019
@rycee
Copy link
Member

rycee commented Aug 21, 2019

@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.

jtojnar added a commit to jtojnar/nixpkgs that referenced this pull request Sep 6, 2019
We had `./options-to-docbook.xsl` as a dependency for `generated` target but it was moved to a package in NixOS#66328.
dtzWill pushed a commit to dtzWill/nixpkgs that referenced this pull request Oct 5, 2019
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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants