nixos-manual: Include all modules in documentation generation #47177
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
/cc @oxij |
|
Ah apparently using |
|
I like the idea, but
- I think you can just add `modules` argument to the top of the whole expression and get the whole list of modules loaded by the current configuration.
- Hence, I expected this to simply add `++ optionals optionName modules` thing after `baseModules`, not to rewrite the whole attribute.
E.g. why did you go from `evalModules` back to `eval-config.nix` and remove all the stuff the old version did with `localSystem`?
|
|
Just my unfamiliarity. I somehow was convinced that the modules argument was not injected into each module by |
arianvp
force-pushed
the
generate-more-docs
branch
2 times, most recently
from
c125e44
to
389494d
Compare
|
I haved used your suggestions! Seems to build now on CI! |
Previously, `man 5 configuration.nix` would only show
options of modules in the `baseModules` set, which
consists only of the list of modules in `nixos/modules/module-list.nix`
however, with this change, any extra module that is included
in your `configuration.nix` file by the means of
```
imports = [ ./rootfs.nix ]
```
will also be included the generated documentation.
Example output:
```
OPTIONS
You can use the following options in configuration.nix.
arian.rootfs.device
The device that contains the btrfs volume
Type: string
Declared by:
/home/arian/Projects/nixos-stuff/computers/t430s/rootfs.nix
boot.enableContainers
Whether to enable support for nixos containers.
Type: boolean
Default: true
Declared by:
<nixpkgs/nixos/modules/virtualisation/containers.nix>
```
I found it useful for my machine to be self-documenting. It also means
that if you import modules like `gce.nix` or `azure.nix` which aren't in
`module-list.nix`, documentation is still generated for these modules
cc: NixOS#11499
- [ ] I have no idea if this patch impacts the way the documentation for https://nixos.org/nixos
is generated. It might. We should check this.
---
arianvp
force-pushed
the
generate-more-docs
branch
from
389494d
to
1f6bf40
Compare
oxij
pushed a commit
to oxij/nixpkgs
that referenced
this pull request
Mar 5, 2019
Before this change `man 5 configuration.nix` would only show options of modules in the `baseModules` set, which consists only of the list of modules in `nixos/modules/module-list.nix` With this change applied and `documentation.nixos.includeAllModules` option enabled all modules included in `configuration.nix` file will be used instead. This makes configurations with custom modules self-documenting. It also means that importing non-`baseModules` modules like `gce.nix` or `azure.nix` will make their documentation available in `man 5 configuration.nix`. `documentation.nixos.includeAllModules` is currently set to `false` by default as enabling it usually uncovers bugs and prevents evaluation. It should be set to `true` in a release or two. This was originally implemented in NixOS#47177, edited for more configurability, documented and rebased onto master by @oxij.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Previously,
man 5 configuration.nixwould only showoptions of modules in the
baseModulesset, whichconsists only of the list of modules in
nixos/modules/module-list.nixhowever, with this change, any extra module that is included
in your
configuration.nixfile by the means ofwill also be included the generated documentation.
Example output:
Motivation for this change
I found it useful for my machine to be self-documenting. It also means
that if you import modules like
gce.nixorazure.nixwhich aren't inmodule-list.nix, documentation is still generated for these modulescc: #11499
Things to do
is generated. It might. We should check this.