Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add manpages #15

Open
water-sucks opened this issue Jul 13, 2024 · 0 comments
Open

docs: add manpages #15

water-sucks opened this issue Jul 13, 2024 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@water-sucks
Copy link
Owner

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?)

@water-sucks water-sucks self-assigned this Jul 13, 2024
@water-sucks water-sucks added the documentation Improvements or additions to documentation label Jul 13, 2024
@water-sucks water-sucks changed the title Add manpages and better documentation docs: add manpages Jul 29, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant