Start generation of the nix.1 manpage

This commit is contained in:
Eelco Dolstra 2020-08-17 19:33:18 +02:00
parent a72a20d68f
commit 6f19c776db
No known key found for this signature in database
GPG key ID: 8170B4726D7198DE
6 changed files with 63 additions and 2 deletions

2
.gitignore vendored
View file

@ -25,6 +25,8 @@ perl/Makefile.config
/doc/manual/*.1
/doc/manual/*.5
/doc/manual/*.8
/doc/manual/nix.json
/doc/manual/src/command-ref/nix.md
# /scripts/
/scripts/nix-profile.sh

View file

@ -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(""))

View file

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

View file

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

View file

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

View file

@ -238,6 +238,7 @@ nlohmann::json Args::toJSON()
}
auto res = nlohmann::json::object();
res["description"] = description();
res["flags"] = std::move(flags);
res["args"] = std::move(args);
return res;
@ -371,7 +372,7 @@ MultiCommand::MultiCommand(const Commands & commands)
: commands(commands)
{
expectArgs({
.label = "command",
.label = "subcommand",
.optional = true,
.handler = {[=](std::string s) {
assert(!command);