Auto-generate store documentation #8084

edolstra · 2023-03-21T13:10:01Z

Motivation

This makes information about the supported store types and their settings in nix help-stores. Store types can now also have some "global" Markdown documentation.

This PR also removes nix describe-stores since we don't actually need it for docs generation and it doesn't really have any other use cases. (If really needed the JSON is still available in the internal nix __dump-cli command.)

Closes #5467. Fixes #6279.

Context

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
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.

This command was intended for docs generation, but it was never used for that and we don't need it.

Why not 'nix help stores'? Well, 'nix help <arg>' already means 'show help on the "arg" subcommand'.

This makes the help commands show up prominently at the top of the 'nix' manpage.

doc/manual/utils.nix

Since setting names are not unique we don't have an easy way to produce unique anchors.

fricklerhandwerk

I can't follow why this is a separate command, while all it does is render documentation. I saw somewhere nix store --help being mentioned in reference to that, but can't find the source. I think that information should simply be on the front page of nix store --help instead.

doc/manual/src/release-notes/rl-next.md

src/libstore/local-store.md

fricklerhandwerk · 2023-03-22T22:00:59Z

src/libstore/local-store.md

+For example, the following uses `/tmp/root` as the chroot environment
+to build or download `nixpkgs#hello` and then execute it:
+
+```console
+# nix run --store /tmp/root nixpkgs#hello
+Hello, world!
+```


I think we should make a definitive decision on whether and how to document experimental features in the stable parts of the manual. Similar situation in the hacking guide.

While this, for now, will only show in nix command docs, there is no reason not to have it everywhere it matters, since that stuff is already stable.

src/libstore/s3-binary-cache-store.cc

src/libstore/legacy-ssh-store.md

fricklerhandwerk · 2023-03-22T22:05:46Z

src/libstore/local-store.md

@@ -0,0 +1,40 @@
+R"(
+
+**Store URL format**: `local`, *root*


I had to read multiple examples to understand that this notation means an enumeration of store formats. There probably is a better way to express this in a way that is immediately clear, but I don't see one yet.

doc/manual/utils.nix

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

edolstra · 2023-03-23T09:19:31Z

I can't follow why this is a separate command, while all it does is render documentation. I saw somewhere nix store --help being mentioned in reference to that, but can't find the source. I think that information should simply be on the front page of nix store --help instead.

That's what this PR originally did, but I think having a nix help-stores is much more discoverable. We could also have nix help-builtins, nix help-settings, etc.

fricklerhandwerk · 2023-03-27T13:37:55Z

Discussed in the Nix team meeting 2023-03-23:

@Ericson2314: very glad we are getting this
@eriscon2314, thufschmitt: it is a bit weird to render the store information under the nix help-stores
- The per-command info should always basically be the man page for that command. In this case, for nix help-stores that would be how to use it, not what it outputs.
- The store info can simply be its own section of the manual, just as other information auto-generated information has its own sections
- Rather than nix help-stores being part of the manual, it should be thought of as a way to view (part of) the manual content from the terminal.
- We should distinguish content vs presentation:
  - the manual is the content
  - the website and nix help-* commands are two alternative presentations of that content.
@edolstra: Sort of makes sense to me; will rework PR.

fricklerhandwerk · 2023-03-27T13:40:32Z

Rather than nix help-stores being part of the manual, it should be thought of as a way to view (part of) the manual content from the terminal.

I'd like to re-iterate that currently our paradigm to view parts of the manual on the command line is nix <subcommand> --help and man <command>. Therefore I don't think having a separate command here is meaningful, as it introduces yet another (inconsistent) way of viewing.

nixos-discourse · 2023-03-27T13:43:35Z

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

https://discourse.nixos.org/t/2023-03-23-nix-team-meeting-minutes-43/26758/1

edolstra · 2023-03-27T13:45:27Z

@edolstra: Sort of makes sense to me; will rework PR.

Just to be clear: the conclusion was that it makes sense to make the store documentation available in the manual in some other location than under nix help-stores, but right now we don't have that. So that could be done in a future PR.

Addressed most comments.

nixos-discourse · 2023-04-02T01:15:11Z

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

https://discourse.nixos.org/t/this-month-in-nix-docs-1-march-2023/26913/1

edolstra added 3 commits March 21, 2023 14:03

nix store --help: Include store type documentation

8d6d59c

nix describe-stores: Remove

7704118

This command was intended for docs generation, but it was never used for that and we don't need it.

Support per-store Markdown documentation

9eb53bb

edolstra requested review from thufschmitt and fricklerhandwerk as code owners March 21, 2023 13:10

github-actions bot added documentation with-tests Issues related to testing. PRs with tests have some priority labels Mar 21, 2023

Formatting

3fc4659

edolstra mentioned this pull request Mar 21, 2023

add documentation for substituter URL options #8071

Closed

7 tasks

edolstra added 2 commits March 21, 2023 14:37

Move store docs to 'nix help-stores'

233b063

Why not 'nix help stores'? Well, 'nix help <arg>' already means 'show help on the "arg" subcommand'.

Add a "help" category

c967c29

This makes the help commands show up prominently at the top of the 'nix' manpage.

symphorien reviewed Mar 21, 2023

View reviewed changes

doc/manual/utils.nix Show resolved Hide resolved

edolstra added 2 commits March 22, 2023 13:11

nix help-stores: Don't include anchors

da8903e

Since setting names are not unique we don't have an easy way to produce unique anchors.

Improve store setting descriptions / Markdown formatting

5691bac

fricklerhandwerk previously requested changes Mar 22, 2023

View reviewed changes

fricklerhandwerk reviewed Mar 22, 2023

View reviewed changes

doc/manual/utils.nix Outdated Show resolved Hide resolved

doc/manual/utils.nix Outdated Show resolved Hide resolved

fricklerhandwerk mentioned this pull request Mar 22, 2023

Merge how-to section on S3 buckets into S3 store docs #7972

Merged

7 tasks

edolstra and others added 6 commits March 23, 2023 09:11

Fix clang build

b134546

Fix SSHStore

80f0b8d

Make useAnchors a named argument

2851e23

showSetting: Drop ...

4d31618

Update src/libstore/local-store.md

abc449b

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

Update doc/manual/src/release-notes/rl-next.md

05d9918

Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>

edolstra added 4 commits March 23, 2023 10:38

Document store URLs

161f4b0

Register LocalStore to ensure it's included in the manual

b79df9d

Update release notes

7a61a9a

Tweaks

168b602

edolstra mentioned this pull request Mar 23, 2023

add HTML anchors for options and environment variables #8097

Closed

7 tasks

thufschmitt added the idea approved The given proposal has been discussed and approved by the Nix team. An implementation is welcome. label Mar 24, 2023

edolstra merged commit 237587b into NixOS:master Mar 27, 2023

edolstra deleted the store-docs branch March 27, 2023 13:46

gador mentioned this pull request Jun 9, 2023

add *.md files to makefile install #8484

Closed

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Auto-generate store documentation #8084

Auto-generate store documentation #8084

edolstra commented Mar 21, 2023 •

edited

Loading

fricklerhandwerk left a comment

fricklerhandwerk Mar 22, 2023

fricklerhandwerk Mar 22, 2023

edolstra commented Mar 23, 2023

fricklerhandwerk commented Mar 27, 2023

fricklerhandwerk commented Mar 27, 2023

nixos-discourse commented Mar 27, 2023

edolstra commented Mar 27, 2023

nixos-discourse commented Apr 2, 2023

Auto-generate store documentation #8084

Auto-generate store documentation #8084

Conversation

edolstra commented Mar 21, 2023 • edited Loading

Motivation

Context

Checklist for maintainers

Priorities

fricklerhandwerk left a comment

Choose a reason for hiding this comment

fricklerhandwerk Mar 22, 2023

Choose a reason for hiding this comment

fricklerhandwerk Mar 22, 2023

Choose a reason for hiding this comment

edolstra commented Mar 23, 2023

fricklerhandwerk commented Mar 27, 2023

fricklerhandwerk commented Mar 27, 2023

nixos-discourse commented Mar 27, 2023

edolstra commented Mar 27, 2023

nixos-discourse commented Apr 2, 2023

edolstra commented Mar 21, 2023 •

edited

Loading