diff options
Diffstat (limited to 'doc/manual')
| -rw-r--r-- | doc/manual/generate-manpage.jq | 42 | ||||
| -rw-r--r-- | doc/manual/local.mk | 8 | ||||
| -rw-r--r-- | doc/manual/src/SUMMARY.md | 2 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/experimental-commands.md | 8 |
4 files changed, 59 insertions, 1 deletions
diff --git a/doc/manual/generate-manpage.jq b/doc/manual/generate-manpage.jq new file mode 100644 index 000000000..cf06da0c8 --- /dev/null +++ b/doc/manual/generate-manpage.jq @@ -0,0 +1,42 @@ +def show_flags: + +.flags +| map_values(select(.category != "config")) +| to_entries +| map( + " - `--" + .key + "`" + + (if .value.shortName then " / `" + .value.shortName + "`" else "" end) + + (if .value.labels then " " + (.value.labels | map("*" + . + "*") | join(" ")) else "" end) + + " \n" + + " " + .value.description + "\n\n") +| join("") +; + +def show_synopsis: + +"`" + .command + "` " + (.args | map("*" + .label + "*" + (if has("arity") then "" else "..." end)) | join(" ")) + "\n" + +; + +"# Synopsis\n\n" ++ ({"command": "nix", "args": .args} | show_synopsis) ++ "\n" ++ "# Common flags\n\n" ++ show_flags ++ (.commands | to_entries | map( + "# Operation `" + .key + "`\n\n" + + "## Synopsis\n\n" + + ({"command": ("nix " + .key), "args": .value.args} | show_synopsis) + + "\n" + + "## Description\n\n" + + .value.description + "\n\n" + + (if (.value.flags | length) > 0 then + "## Flags\n\n" + + (.value | show_flags) + else "" end) + + (if (.value.examples | length) > 0 then + "## Examples\n\n" + + (.value.examples | map("- " + .description + "\n\n ```console\n " + .command + "\n ```\n" ) | join("\n")) + + "\n" + else "" end) + ) | join("")) diff --git a/doc/manual/local.mk b/doc/manual/local.mk index c9104ad7e..8f917316d 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -4,7 +4,7 @@ MANUAL_SRCS := $(call rwildcard, $(d)/src, *.md) # Generate man pages. man-pages := $(foreach n, \ - nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 \ + nix-env.1 nix-build.1 nix-shell.1 nix-store.1 nix-instantiate.1 nix.1 \ nix-collect-garbage.1 \ nix-prefetch-url.1 nix-channel.1 \ nix-hash.1 nix-copy-closure.1 \ @@ -24,6 +24,12 @@ $(d)/%.8: $(d)/src/command-ref/%.md $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md $(trace-gen) lowdown -sT man $^ -o $@ +$(d)/src/command-ref/nix.md: $(d)/nix.json $(d)/generate-manpage.jq + jq -r -f doc/manual/generate-manpage.jq $< > $@ + +$(d)/nix.json: $(bindir)/nix + $(trace-gen) $(bindir)/nix dump-args > $@ + # Generate the HTML manual. install: $(docdir)/manual/index.html diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md index 5f6817674..4089caf8a 100644 --- a/doc/manual/src/SUMMARY.md +++ b/doc/manual/src/SUMMARY.md @@ -60,6 +60,8 @@ - [nix-hash](command-ref/nix-hash.md) - [nix-instantiate](command-ref/nix-instantiate.md) - [nix-prefetch-url](command-ref/nix-prefetch-url.md) + - [Experimental Commands](command-ref/experimental-commands.md) + - [nix](command-ref/nix.md) - [Files](command-ref/files.md) - [nix.conf](command-ref/conf-file.md) - [Glossary](glossary.md) diff --git a/doc/manual/src/command-ref/experimental-commands.md b/doc/manual/src/command-ref/experimental-commands.md new file mode 100644 index 000000000..cfa6f8b73 --- /dev/null +++ b/doc/manual/src/command-ref/experimental-commands.md @@ -0,0 +1,8 @@ +# Experimental Commands + +This section lists experimental commands. + +> **Warning** +> +> These commands may be removed in the future, or their syntax may +> change in incompatible ways. |