Feature/documentation request: local documentation generation

[shanesveller]

I've seen the wizardry you've used and now extracted into the flake.parts-website repository for generating single-page documentation from the in-code description/examples and would love to be able to adapt that technique to my own public flake modules. I plan to review that code soon, as well as whatever is used for home-manager's equivalent.

Incidentally this capability would also help me reason my way through my confusion around top-level vs perSystem options I posted here.

[roberth]

I think the way to go here is to make the website repo expose a function for this purpose.

The documentation generation story is in flux at the moment, with the NixOS logic moving towards markdown, with a simplified toolchain and other (extensive) improvements such as NixOS/nixpkgs#199363 coming.

Home-manager uses its own docs library that was around the time that Nixpkgs started exposing the module docs logic. We should all converge to a single, sensible, standard implementation, for which the best place is the nixpkgs repository.

[adrian-gierakowski]

The kubenix website\docs might be of interest as well.

script to generate the docs

nix code which generates options.json from module definitions.

One thing the website is lacking is options search, similar to the one for nixos

[roberth]

I'm quite happy to accept PRs to https://github.com/hercules-ci/flake.parts-website, after which you can use that repo to build your own docs. Doing it this way also helps with discoverability of your public modules.

I'm going to hold off reusability improvements to flake.parts-website until the upstream documentation generation stabilizes. Nixpkgs currently has a lot going on regarding the completion of the markdown migration and some interface changes around nixosOptionsDoc.

[terlar]

I guess not much has changed regarding this situation. But another use case that I myself ran into now is that I have non-public flake-parts modules used internally at a company. I was looking a bit at the flake.parts-website and it would be nice to manually run some of those flows. Generating documentation for nix module system is something that really makes them shine. :)

Would it be worth looking into exposing some of those modules or should I hold off to something more aligned has landed in nixpkgs and the nix community as a whole?

[roberth]

If your module is already published, you can do something like the following. I'll use hercules-ci-effects as an example

cd hercules-ci-effects
nix build github:hercules-ci/flake.parts-website --override-input hercules-ci-effects .

You could even run this in a Hercules CI effect or in a traditional CLI-first CI.
It's also possible to make flake.parts-website a flake input and use follows to the same effect. That's more reproducible, but bloats your consumers' lock files a bit. (Which is a Nix bug afaic NixOS/nix#7730)

For private modules this still needs a bit of work though. The way the website is set up, it uses the module system to configure the site (of course!) and it could expose a function to extend that "site configuration".