Every NixOS module should have a section in the manual

[mightyiam]

Problem

Not every NixOS module has a section in the manual.

A user searching through the manual for a certain software in order to determine whether a module for it exists, may arrive at the conclusion that no such module exists, when they find that a section for that software does not exist in the manual.

Such a conclusion could be wrong because not every NixOS module has a section in the manual.

Checklist

• checked latest Nixpkgs manual (source) and latest NixOS manual] [source]nixos-source)
• checked open documentation issues for possible duplicates
• checked open documentation pull requests for possible solutions

Proposal

A section in the manual is auto-generated for each NixOS module, regardless of whether they have explicitly written documentation.

At the very least the section will contain links to the options provided by the module.

Any explicitly authored documentation will be appended to the autogenerated one.

NixOS modules which, for any reason, should not have a section in the manual (if such exist), will be explicitly excluded.

Co-authored-by @a-kenji

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/usability-study-session-4/21422/1

[dit7ya]

Request for comments

I think documentation is a good area for Hacktoberfest PRs. And this issue can become a meta-issue for multiple such PRs.

[jansol]

Pipewire is one such module, see #102547

[MichaelAkvo]

I just stumbled upon this issue when trying to find a way to install components for google cloud sdk. The solution is not documented and I was lucky to find it in the issue. Not only modules but functions should also generate documentation. Python has doc-strings and it seems like there's something like that scattered around the .nix files in this repo, but no documentation seems to be generated from this.

Rust does an amazing job at generating documentation that is easily readable and probably a decade or more before that Java started doing the same with javadoc. IMO this should be the ultimate goal of the nixpkgs reference documentation: run a command that parses .nix files and generates documentation from them. If possible even allow for the examples in the docs to act as tests, just like in Rust.

[mightyiam]

@MichaelAkvo see this discussion.