You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
man is probably the best way to distribute long-form documentation for this application. There is a lot of behavior that is basically undocumented, such as:
env variables such as NIXOS_CONFIG, NIXOS_CLI_CONFIG, etc.
flake vs. non-flake differences in behavior
many others
Since the argument parser is hand-rolled (not very well, but I digress), it's probably best to do this separately from all of the code, and manually ensure that it is maintained properly whenever new options are added through code review processes. It should be easy to audit when options and subcommands are added, and update the documentation as seen fit.
Different subcommands will have their own manpages, similar to git. This allows for easier discovery of options and behavior across subcommands.
The simplest tool to use for writing manpages, after doing some research, looks to be scdoc. This can be integrated as an external command in the Zig build system, that can be controlled with an option to generate documentation or not. As much as options like mdbook exist, I would prefer to not use that, because this tool is a CLI tool, and I would rather not deal with the intricacies of generating static websites for documentation when that documentation can be accessed right where you use the command (and who the hell is running nixos apply from a browser instead of a TTY, anyway?)
The text was updated successfully, but these errors were encountered:
man
is probably the best way to distribute long-form documentation for this application. There is a lot of behavior that is basically undocumented, such as:NIXOS_CONFIG
,NIXOS_CLI_CONFIG
, etc.Since the argument parser is hand-rolled (not very well, but I digress), it's probably best to do this separately from all of the code, and manually ensure that it is maintained properly whenever new options are added through code review processes. It should be easy to audit when options and subcommands are added, and update the documentation as seen fit.
Different subcommands will have their own manpages, similar to
git
. This allows for easier discovery of options and behavior across subcommands.The simplest tool to use for writing manpages, after doing some research, looks to be
scdoc
. This can be integrated as an external command in the Zig build system, that can be controlled with an option to generate documentation or not. As much as options likemdbook
exist, I would prefer to not use that, because this tool is a CLI tool, and I would rather not deal with the intricacies of generating static websites for documentation when that documentation can be accessed right where you use the command (and who the hell is runningnixos apply
from a browser instead of a TTY, anyway?)The text was updated successfully, but these errors were encountered: