Document each store implementation on its own page by Ericson2314 · Pull Request #8781 · NixOS/nix

Ericson2314 · 2023-08-04T05:23:03Z

Motivation

This makes for more useful manual table of contents, that displays the information at a glance.

Context

The nix help-stores command is kept as-is, even though it will show up in the manual with the same information as these pages due to the way it is written as a "--help-style" command. Deciding what to do with that command is left for a later PR.

Checklist for maintainers

Maintainers: tick if completed or explain if not relevant

agreed on idea
agreed on implementation strategy
tests, as appropriate
- functional tests - tests/**.sh
- unit tests - src/*/tests
- integration tests - tests/nixos/*
documentation in the manual
documentation in the internal API docs
code and comments are self-explanatory
commit message explains why the change was made
new feature or incompatible change: updated release notes

Priorities

Add 👍 to pull requests you find important.

fricklerhandwerk

Needs a release note that nix help-stores was removed again.

doc/manual/generate-store-implementation.nix

Ericson2314 · 2023-08-04T20:23:26Z

Triaged in the Nix Team meeting this morning (n.b. I could not make it)

@edolstra:
- Removing nix help-stores isn't great, we want that on the manpage
  - Need something of an equivalent
- Is splitting it really an improvement?

Queued for further discussion

fricklerhandwerk · 2023-08-05T09:26:02Z

Why not put it on nix-store --help and nix store --help? There is not much else there, and it's an obvious place to look for. Adding a brief intro referencing where those parameters used, such as common options, would remove all ambiguities.

Ericson2314 · 2023-08-07T00:31:29Z

Putting it in commands competes with @fricklerhandwerk's goal of making manual text changes not rebuild the Nix command. This is a relatively new thing so their isn't an existing expectation for a man page and command. I rather take the opportunity to turn it into a 0 rebuild demonstration and then add back functionality in the command later.

I think the more useful command to have is something like nix store show-config which shows the live current store settings.

nixos-discourse · 2023-08-09T05:14:15Z

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

https://discourse.nixos.org/t/2023-08-04-nix-team-meeting-minutes-77/31487/1

fricklerhandwerk · 2023-08-23T07:29:27Z

Reviewed and discussed in Nix team meeting 2023-08-21:

decision:
- nix help no longer shows --help, and --help only shows brief listings about the command
- rename the category to "Store types"
- add more cross-references
- make the symbolic names all lower case
- postpone this PR for now, focus on improving internal structure

Tasks:

terse --help (i.e. not about rendered pages)
- add shortDescription to flags (plain text, no markdown)
- add shortDescription to commands (same)
- make --help distinct from nix help
  - show listing for command groups
  - show listing for (sub)command options and refer to nix help <group> <command>
view documents from help (i.e. not just CLI commands)
- nix help <topic>
sync the html manual TOC and the CLI topic page TOC

Complete discussion

@edolstra: should be called store types
@fricklerhandwerk: should at least have a listing of those
@roberth: I'd expect to have man pages that are not about commands
- e.g. man nix-store-local
- @edolstra: have to consider that with statically linked nix binary we don't have man pages
  - @roberth: seems excessive to bundle all the manual contents with the binary. Users expect a lightweight static executable
  - @edolstra: alternative is to remove most of the manual and tell people to read the webpage
    - man pages are an outdated format and may not be available
    - @roberth: if we wanted to abstract from man, we could have nix help do the job and essentially render all documentation pages on the terminal, e.g. nix help store-types-ssh.
      - First looks for commands, if no command, looks for pages
      - Otherwise, against having a ton of custom commands for documentation
        
        @edolstra: actually in favor of more commands, e.g. things about configuration should be shown under nix help --config
    - @Ericson2314: That would help with avoiding rebuilds too
    - @fricklerhandwerk: rather not, that would preclude accessing the information right away
@roberth: proposal: mention a new manpage (and link to online page), then don't have to include it in the static binary
- @edolstra: we don't reference man pages anywhere. man is just a rendering mechanism, should just have hyperlinks
- @fricklerhandwerk: discussed this in the past, can't point to domains – will be stuck forever without versioned manuals, and cannot track change of domains (which is not impossible)
  - @Ericson2314: how do man pages reference other manpages?
  - @fricklerhandwerk: textually, and ideally we'd have automatic conversion for the different outputs, but we don't have the infrastructure for that
  - @roberth: could link file:///nix/store urls, only doesn't work over ssh
@Ericson2314:
- Can list store types on the settings page with links just as we do for experimental features
@fricklerhandwerk: the problem is that those special help commands are very hard to discover and cover cross-cutting concerns
@edolstra: ideally we'd have more such help pages for concepts, such as the language
- @roberth: in that case we woulnd't have separate pages for every little thing but rather bundle non-command documentation under nix help
  - agreement
  - @roberth: nix <command> --help should only have a terse listing of subcommands and options, and everything else should be accessible under nix help <topic> <subtopic>. this would support homogeneous structure across manual and "man pages"
    - @Ericson2314: agreed
    - @fricklerhandwerk: makes sense. nix help could just be a hierarchical page viewer
decision:
- nix help no longer shows --help, and --help only shows brief listings about the command
- rename the category to "Store types"
- add more cross-references
- make the symbolic names all lower case
- postpone this PR for now, focus on improving internal structure

Tasks:

terse --help (i.e. not about rendered pages)
- add shortDescription to flags (plain text, no markdown)
- add shortDescription to commands (same)
- make --help distinct from nix help
  - show listing for command groups
  - show listing for (sub)command options and refer to nix help <group> <command>
view documents from help (i.e. not just CLI commands)
- nix help <topic>
sync the html manual TOC and the CLI topic page TOC

nixos-discourse · 2023-08-23T07:33:56Z

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

https://discourse.nixos.org/t/2023-08-21-nix-team-meeting-minutes-81/32082/1

Ericson2314 · 2023-10-25T03:36:48Z

OK now that nix help-stores is left the same as before, I think there is nothing controversial about this and it is ready to go.

fricklerhandwerk · 2023-10-25T10:17:35Z

Looks good in general, but I need some time to look at it in detail.

nixos-discourse · 2023-11-27T16:08:47Z

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

https://discourse.nixos.org/t/2023-11-27-nix-team-meeting-minutes-107/36112/1

this makes the files in question a bit more independent of source location. to find where the value is set and how it's wired up: rg nix=doc/manual

This makes for more useful manual table of contents, that displays the information at a glance. The `nix help-stores` command is kept as-is, even though it will show up in the manual with the same information as these pages due to the way it is written as a "`--help`-style" command. Deciding what to do with that command is left for a later PR.

fricklerhandwerk · 2023-11-30T23:00:48Z

Closing in favor of #9504 as discussed.

Ericson2314 requested review from edolstra, fricklerhandwerk and thufschmitt as code owners August 4, 2023 05:23

github-actions bot added documentation new-cli Relating to the "nix" command labels Aug 4, 2023

fricklerhandwerk approved these changes Aug 4, 2023

View reviewed changes

fricklerhandwerk mentioned this pull request Aug 12, 2023

Make a separate manual page for store implementations #8496

Closed

Ericson2314 force-pushed the store-implementation-per-page branch from c6fc70c to 0af25ac Compare August 21, 2023 12:59

github-actions bot added the store Issues and pull requests concerning the Nix store label Aug 21, 2023

Ericson2314 force-pushed the store-implementation-per-page branch from 0af25ac to fe98131 Compare October 13, 2023 05:30

Ericson2314 force-pushed the store-implementation-per-page branch 4 times, most recently from a304987 to 1637919 Compare October 25, 2023 03:36

Ericson2314 assigned fricklerhandwerk Oct 25, 2023

Ericson2314 force-pushed the store-implementation-per-page branch 2 times, most recently from 105e6b4 to 644e34e Compare November 4, 2023 23:07

Ericson2314 force-pushed the store-implementation-per-page branch from 644e34e to 99c923f Compare November 25, 2023 04:52

Ericson2314 requested a review from roberth as a code owner November 25, 2023 04:52

Ericson2314 force-pushed the store-implementation-per-page branch from 99c923f to d3973f4 Compare November 30, 2023 18:02

fricklerhandwerk mentioned this pull request Nov 30, 2023

Keep generated documentation for --help in a separate directory #9500

Merged

Ericson2314 force-pushed the store-implementation-per-page branch from d3973f4 to 98d2db0 Compare November 30, 2023 20:40

fricklerhandwerk and others added 2 commits November 30, 2023 21:53

use lookup paths in helper expressions consistently

d5ffc94

this makes the files in question a bit more independent of source location. to find where the value is set and how it's wired up: rg nix=doc/manual

Ericson2314 force-pushed the store-implementation-per-page branch from 98d2db0 to 2a8e49a Compare November 30, 2023 21:03

fricklerhandwerk mentioned this pull request Nov 30, 2023

Document each store type on its own page #9504

Merged

fricklerhandwerk closed this Nov 30, 2023

Ericson2314 deleted the store-implementation-per-page branch November 30, 2023 23:40

Uh oh!

Conversation

Ericson2314 commented Aug 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Context

Checklist for maintainers

Priorities

Uh oh!

fricklerhandwerk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Ericson2314 commented Aug 4, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fricklerhandwerk commented Aug 5, 2023

Uh oh!

Ericson2314 commented Aug 7, 2023

Uh oh!

nixos-discourse commented Aug 9, 2023

Uh oh!

fricklerhandwerk commented Aug 23, 2023

Uh oh!

nixos-discourse commented Aug 23, 2023

Uh oh!

Ericson2314 commented Oct 25, 2023

Uh oh!

fricklerhandwerk commented Oct 25, 2023

Uh oh!

nixos-discourse commented Nov 27, 2023

Uh oh!

fricklerhandwerk commented Nov 30, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Ericson2314 commented Aug 4, 2023 •

edited

Loading

Ericson2314 commented Aug 4, 2023 •

edited

Loading