Documentation for custom NixOS options

I did a few quick searches and didn’t come back with any results so I thought I’d ask here before digging into code:

Is there an easy way to print all the NixOS options from my custom modules into an HTML page like the NixOS manual?

For bonus points, is there a way to publish my own internal searchable interface to the options from my custom modules like NixOS Search - Loading...?

Any and all help appreciated :bowing_man:

2 Likes

The documentation.nixos.* options allow you to gather option documentation from custom modules if you want, for the html manual and the man page. I don’t know about a custom search interface, though.

Thanks for your comments. I should have specified that I want to publish this and possibly even build it from a non NixOS machine. Taking a quick look at the code it seems like with some experimenting I can probably get what I want. Hopefully there is a way to easily exclude the built-in NixOS modules… I only want to publish my own.

ping @garbas @davidak because they probably know how to put together a site that can search my options.
ping @roberth because he printed options for some of his stuff.

:heart:

The magic word is pkgs.nixosOptionsDoc aka nixos/lib/make-options-doc.

I’m not super happy about that interface, as it tries to do too much at once, but it gets the job done.
We could perhaps clean it up after the migration to markdown option docs. Wouldn’t hurt to have some docs then either.

As for search, the search.nixos.org is powered by an elasticsearch backend, which is probably a bit heavy a solution for smaller projects. Some static doc site generators have client side search now, specifically mdbook, which is used by the somewhat recently refreshed Nix manual.

3 Likes

I almost exclusively use the configuration.nix manual pages for quick option searches. The browser seems to be infinitely slower and is just annoying. Does this work for the manual pages as well? I’ve been wondering that for a while but haven’t had a chance to look further.

This does not answer your use case, but this might answer uses cases of other NixOS users.

There is an option named documentation.nixos.includeAllModules. Which was initially set to true but switched to false due to performance/rebuild concerns from NixOps users.

Maybe we could enable it by default for desktop users, as it literally output in man configuration.nix all options, including your own modules.