From 725f5cd358b2a3906a1922017fa424666a972758 Mon Sep 17 00:00:00 2001 From: eldritch horrors Date: Mon, 8 Apr 2024 21:44:40 +0200 Subject: docs: redo content generation for mdbook and manual manpages can be rendered using the markdown output of mdbook, the rest of the manual can generated out of the main doc/manual source tree. we still use lowdown to actually render manpages instead of eg mdbook-man because lowdown does generate reasonably good manpages (though that is also somewhat debatable, but they're a lot better than mdbook-man). doing this not only lets us drastically simplify the lowdown pipeline, but also remove all custom {{#include}} handling since now mdbook does all of it, even for the manpage builds. even the lowdown wrapper isn't entirely necessary because lowdown can take all wrapper arguments with command line flags rather than bits of input file content. This also implements running mdbook in Meson, in order to generate the manpages. The mdbook outputs are also installed in the usual location. Co-authored-by: Qyriad Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b --- .gitignore | 4 - doc/manual/book.toml | 20 +-- doc/manual/docroot.py | 84 ---------- doc/manual/generate-deps.py | 22 +++ doc/manual/local.mk | 97 +++++++----- doc/manual/meson.build | 175 +++++++++++++-------- doc/manual/render-manpage.sh | 17 +- doc/manual/src/command-ref/conf-file-prefix.md | 69 -------- doc/manual/src/command-ref/conf-file.md | 71 +++++++++ doc/manual/src/command-ref/meson.build | 65 ++++++++ doc/manual/src/command-ref/new-cli/nix.md | 1 + doc/manual/src/command-ref/new-cli/nix3-build.md | 1 + doc/manual/src/command-ref/new-cli/nix3-bundle.md | 1 + doc/manual/src/command-ref/new-cli/nix3-copy.md | 1 + doc/manual/src/command-ref/new-cli/nix3-daemon.md | 1 + .../src/command-ref/new-cli/nix3-derivation-add.md | 1 + .../command-ref/new-cli/nix3-derivation-show.md | 1 + .../src/command-ref/new-cli/nix3-derivation.md | 1 + doc/manual/src/command-ref/new-cli/nix3-develop.md | 1 + doc/manual/src/command-ref/new-cli/nix3-doctor.md | 1 + doc/manual/src/command-ref/new-cli/nix3-edit.md | 1 + doc/manual/src/command-ref/new-cli/nix3-eval.md | 1 + .../src/command-ref/new-cli/nix3-flake-archive.md | 1 + .../src/command-ref/new-cli/nix3-flake-check.md | 1 + .../src/command-ref/new-cli/nix3-flake-clone.md | 1 + .../src/command-ref/new-cli/nix3-flake-info.md | 1 + .../src/command-ref/new-cli/nix3-flake-init.md | 1 + .../src/command-ref/new-cli/nix3-flake-lock.md | 1 + .../src/command-ref/new-cli/nix3-flake-metadata.md | 1 + .../src/command-ref/new-cli/nix3-flake-new.md | 1 + .../src/command-ref/new-cli/nix3-flake-prefetch.md | 1 + .../src/command-ref/new-cli/nix3-flake-show.md | 1 + .../src/command-ref/new-cli/nix3-flake-update.md | 1 + doc/manual/src/command-ref/new-cli/nix3-flake.md | 1 + doc/manual/src/command-ref/new-cli/nix3-fmt.md | 1 + .../src/command-ref/new-cli/nix3-hash-file.md | 1 + .../src/command-ref/new-cli/nix3-hash-path.md | 1 + .../src/command-ref/new-cli/nix3-hash-to-base16.md | 1 + .../src/command-ref/new-cli/nix3-hash-to-base32.md | 1 + .../src/command-ref/new-cli/nix3-hash-to-base64.md | 1 + .../src/command-ref/new-cli/nix3-hash-to-sri.md | 1 + doc/manual/src/command-ref/new-cli/nix3-hash.md | 1 + .../src/command-ref/new-cli/nix3-help-stores.md | 1 + doc/manual/src/command-ref/new-cli/nix3-help.md | 1 + .../new-cli/nix3-key-convert-secret-to-public.md | 1 + .../new-cli/nix3-key-generate-secret.md | 1 + doc/manual/src/command-ref/new-cli/nix3-key.md | 1 + doc/manual/src/command-ref/new-cli/nix3-log.md | 1 + doc/manual/src/command-ref/new-cli/nix3-nar-cat.md | 1 + .../src/command-ref/new-cli/nix3-nar-dump-path.md | 1 + doc/manual/src/command-ref/new-cli/nix3-nar-ls.md | 1 + doc/manual/src/command-ref/new-cli/nix3-nar.md | 1 + .../src/command-ref/new-cli/nix3-path-info.md | 1 + .../src/command-ref/new-cli/nix3-print-dev-env.md | 1 + .../new-cli/nix3-profile-diff-closures.md | 1 + .../command-ref/new-cli/nix3-profile-history.md | 1 + .../command-ref/new-cli/nix3-profile-install.md | 1 + .../src/command-ref/new-cli/nix3-profile-list.md | 1 + .../src/command-ref/new-cli/nix3-profile-remove.md | 1 + .../command-ref/new-cli/nix3-profile-rollback.md | 1 + .../command-ref/new-cli/nix3-profile-upgrade.md | 1 + .../new-cli/nix3-profile-wipe-history.md | 1 + doc/manual/src/command-ref/new-cli/nix3-profile.md | 1 + .../command-ref/new-cli/nix3-realisation-info.md | 1 + .../src/command-ref/new-cli/nix3-realisation.md | 1 + .../src/command-ref/new-cli/nix3-registry-add.md | 1 + .../src/command-ref/new-cli/nix3-registry-list.md | 1 + .../src/command-ref/new-cli/nix3-registry-pin.md | 1 + .../command-ref/new-cli/nix3-registry-remove.md | 1 + .../src/command-ref/new-cli/nix3-registry.md | 1 + doc/manual/src/command-ref/new-cli/nix3-repl.md | 1 + doc/manual/src/command-ref/new-cli/nix3-run.md | 1 + doc/manual/src/command-ref/new-cli/nix3-search.md | 1 + doc/manual/src/command-ref/new-cli/nix3-shell.md | 1 + .../src/command-ref/new-cli/nix3-show-config.md | 1 + .../src/command-ref/new-cli/nix3-store-add-file.md | 1 + .../src/command-ref/new-cli/nix3-store-add-path.md | 1 + .../src/command-ref/new-cli/nix3-store-cat.md | 1 + .../src/command-ref/new-cli/nix3-store-copy-log.md | 1 + .../command-ref/new-cli/nix3-store-copy-sigs.md | 1 + .../src/command-ref/new-cli/nix3-store-delete.md | 1 + .../new-cli/nix3-store-diff-closures.md | 1 + .../command-ref/new-cli/nix3-store-dump-path.md | 1 + .../src/command-ref/new-cli/nix3-store-gc.md | 1 + .../src/command-ref/new-cli/nix3-store-ls.md | 1 + .../new-cli/nix3-store-make-content-addressed.md | 1 + .../src/command-ref/new-cli/nix3-store-optimise.md | 1 + .../new-cli/nix3-store-path-from-hash-part.md | 1 + .../src/command-ref/new-cli/nix3-store-ping.md | 1 + .../new-cli/nix3-store-prefetch-file.md | 1 + .../src/command-ref/new-cli/nix3-store-repair.md | 1 + .../src/command-ref/new-cli/nix3-store-sign.md | 1 + .../src/command-ref/new-cli/nix3-store-verify.md | 1 + doc/manual/src/command-ref/new-cli/nix3-store.md | 1 + .../src/command-ref/new-cli/nix3-upgrade-nix.md | 1 + .../src/command-ref/new-cli/nix3-why-depends.md | 1 + .../src/contributing/experimental-features.md | 2 +- doc/manual/src/contributing/meson.build | 15 ++ .../src/language/builtin-constants-prefix.md | 5 - .../src/language/builtin-constants-suffix.md | 1 - doc/manual/src/language/builtin-constants.md | 9 ++ doc/manual/src/language/builtins-prefix.md | 16 -- doc/manual/src/language/builtins-suffix.md | 1 - doc/manual/src/language/builtins.md | 20 +++ doc/manual/src/language/meson.build | 27 ++++ doc/manual/src/release-notes/meson.build | 20 +++ doc/manual/src/release-notes/rl-next.md | 2 +- doc/manual/substitute.py | 101 ++++++++++++ meson.build | 4 + src/libutil/config.hh | 2 +- 110 files changed, 628 insertions(+), 307 deletions(-) delete mode 100755 doc/manual/docroot.py create mode 100755 doc/manual/generate-deps.py delete mode 100644 doc/manual/src/command-ref/conf-file-prefix.md create mode 100644 doc/manual/src/command-ref/conf-file.md create mode 100644 doc/manual/src/command-ref/meson.build create mode 100644 doc/manual/src/command-ref/new-cli/nix.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-build.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-bundle.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-copy.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-daemon.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-derivation-add.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-derivation-show.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-derivation.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-develop.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-doctor.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-edit.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-eval.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-archive.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-check.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-clone.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-info.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-init.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-lock.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-new.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-show.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake-update.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-flake.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-fmt.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-file.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-path.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-hash.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-help-stores.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-help.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-key.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-log.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-nar-cat.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-nar-ls.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-nar.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-path-info.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-history.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-install.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-list.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-remove.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-profile.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-realisation-info.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-realisation.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-registry-add.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-registry-list.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-registry-pin.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-registry-remove.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-registry.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-repl.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-run.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-search.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-shell.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-show-config.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-add-file.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-add-path.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-cat.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-copy-log.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-copy-sigs.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-delete.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-diff-closures.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-dump-path.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-gc.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-ls.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-make-content-addressed.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-optimise.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-path-from-hash-part.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-ping.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-prefetch-file.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-repair.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-sign.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store-verify.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-store.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-upgrade-nix.md create mode 100644 doc/manual/src/command-ref/new-cli/nix3-why-depends.md create mode 100644 doc/manual/src/contributing/meson.build delete mode 100644 doc/manual/src/language/builtin-constants-prefix.md delete mode 100644 doc/manual/src/language/builtin-constants-suffix.md create mode 100644 doc/manual/src/language/builtin-constants.md delete mode 100644 doc/manual/src/language/builtins-prefix.md delete mode 100644 doc/manual/src/language/builtins-suffix.md create mode 100644 doc/manual/src/language/builtins.md create mode 100644 doc/manual/src/language/meson.build create mode 100644 doc/manual/src/release-notes/meson.build create mode 100755 doc/manual/substitute.py diff --git a/.gitignore b/.gitignore index d25f6310f..8f2c69dea 100644 --- a/.gitignore +++ b/.gitignore @@ -21,12 +21,8 @@ perl/Makefile.config /doc/manual/conf-file.json /doc/manual/language.json /doc/manual/xp-features.json -/doc/manual/src/command-ref/new-cli -/doc/manual/src/command-ref/conf-file.md /doc/manual/src/command-ref/experimental-features-shortlist.md /doc/manual/src/contributing/experimental-feature-descriptions.md -/doc/manual/src/language/builtins.md -/doc/manual/src/language/builtin-constants.md /doc/manual/src/release-notes/rl-next-generated.md # /scripts/ diff --git a/doc/manual/book.toml b/doc/manual/book.toml index e03bed737..ae4ff9b35 100644 --- a/doc/manual/book.toml +++ b/doc/manual/book.toml @@ -7,20 +7,22 @@ additional-js = ["redirects.js"] edit-url-template = "https://github.com/NixOS/nix/tree/master/doc/manual/{path}" git-repository-url = "https://github.com/NixOS/nix" -# Handles replacing @docroot@ with a path to ./src relative to that markdown file. -[preprocessor.docroot] -renderers = ["html", "linkcheck"] -command = "python3 doc/manual/docroot.py" -# I would have thought that @docroot@ replacement had to be done *before* -# the link preprocessor gets its hands on this book, but nope it's actually -# the opposite. -after = ["links"] -before = ["anchors"] +# Handles replacing @docroot@ with a path to ./src relative to that markdown file, +# {{#include handlebars}}, and the @generated@ syntax used within these. it mostly +# but not entirely replaces the links preprocessor (which we cannot simply use due +# to @generated@ files living in a different directory to make meson happy). we do +# not want to disable the links preprocessor entirely though because that requires +# disabling *all* built-in preprocessors and selectively reenabling those we want. +[preprocessor.substitute] +command = "python3 doc/manual/substitute.py" +before = ["anchors", "links"] [preprocessor.anchors] renderers = ["html"] command = "jq --from-file doc/manual/anchors.jq" +[output.markdown] + [output.linkcheck] # no Internet during the build (in the sandbox) follow-web-links = false diff --git a/doc/manual/docroot.py b/doc/manual/docroot.py deleted file mode 100755 index e95f8abbf..000000000 --- a/doc/manual/docroot.py +++ /dev/null @@ -1,84 +0,0 @@ -#!/usr/bin/env python3 - -from pathlib import Path -import json -import os, os.path -import sys - -name = 'process-docroot.py' - -def log(*args, **kwargs): - kwargs['file'] = sys.stderr - return print(f'{name}:', *args, **kwargs) - -def replace_docroot(relative_md_path: Path, content: str, book_root: Path): - assert not relative_md_path.is_absolute(), f'{relative_md_path=} from mdbook should be relative' - - md_path_abs = book_root / relative_md_path - docroot_abs = md_path_abs.parent - assert docroot_abs.is_dir(), f'supposed docroot {docroot_abs} is not a directory (cwd={os.getcwd()})' - - # The paths mdbook gives us are relative to the directory with book.toml. - # @docroot@ wants to be replaced with the path relative to `src/`. - docroot_rel = os.path.relpath(book_root / 'src', start=docroot_abs) - - return content.replace('@docroot@', docroot_rel) - -def recursive_replace(data, book_root): - match data: - case {'sections': sections}: - return data | dict( - sections = [recursive_replace(section, book_root) for section in sections], - ) - case {'Chapter': chapter}: - # Path to the .md file for this chapter, relative to book_root. - path_to_chapter = Path('src') / chapter['path'] - chapter_content = chapter['content'] - - return data | dict( - Chapter = chapter | dict( - content = replace_docroot(path_to_chapter, chapter_content, book_root), - sub_items = [recursive_replace(sub_item, book_root) for sub_item in chapter['sub_items']], - ), - ) - - case rest: - assert False, f'should have been called on a dict, not {type(rest)=}\n\t{rest=}' - -def main(): - - if len(sys.argv) > 1 and sys.argv[1] == 'supports': - log('confirming to mdbook that we support their stuff') - return 0 - - # mdbook communicates with us over stdin and stdout. - # It splorks us a JSON array, the first element describing the context, - # the second element describing the book itself, - # and then expects us to send it the modified book JSON over stdout. - - context, book = json.load(sys.stdin) - - # book_root is *not* @docroot@. @docroot@ gets replaced with a relative path to `./src/`. - # book_root is the directory where book.toml, aka `src`'s parent. - book_root = Path(context['root']) - assert book_root.exists(), f'{book_root=} does not exist' - assert book_root.joinpath('book.toml').is_file(), f'{book_root / "book.toml"} is not a file' - - log('replacing all occurrences of @docroot@ with a relative path') - - # Find @docroot@ in all parts of our recursive book structure. - replaced_content = recursive_replace(book, book_root) - - replaced_content_str = json.dumps(replaced_content) - - # Give mdbook our changes. - print(replaced_content_str) - - log('done!') - -try: - sys.exit(main()) -except AssertionError as e: - print(f'{name}: INTERNAL ERROR in mdbook preprocessor', file=sys.stderr) - print(f'this is a bug in {name}') - raise diff --git a/doc/manual/generate-deps.py b/doc/manual/generate-deps.py new file mode 100755 index 000000000..297bd3939 --- /dev/null +++ b/doc/manual/generate-deps.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python3 + +import glob +import sys + +# meson expects makefile-style dependency declarations, i.e. +# +# target: dependency... +# +# meson seems to pass depfiles straight on to ninja even though +# it also parses the file itself (or at least has code to do so +# in its tree), so we must live by ninja's rules: only slashes, +# spaces and octothorpes can be escaped, anything else is taken +# literally. since the rules for these aren't even the same for +# all three we will just fail when we encounter any of them (if +# asserts are off for some reason the depfile will likely point +# to nonexistant paths, making everything phony and thus fine.) +for path in glob.glob(sys.argv[1] + '/**', recursive=True): + assert '\\' not in path + assert ' ' not in path + assert '#' not in path + print("ignored:", path) diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 13ab6da2f..215609f79 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -17,14 +17,14 @@ man-pages := $(foreach n, \ nix-hash.1 nix-copy-closure.1 \ nix.conf.5 nix-daemon.8 \ nix-profiles.5 \ -, $(d)/$(n)) +, doc/manual/generated/in/$(n)) # man pages for subcommands # convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1` # FIXME: unify with how nix3-cli man pages are generated man-pages += $(foreach subcommand, \ $(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/src/command-ref/nix-*/*.md)), \ - $(d)/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand))))) + doc/manual/generated/in/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand))))) clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8 @@ -39,77 +39,91 @@ dummy-env = env -i \ nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw -$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md +doc/manual/generated/in/nix-env-%.1: doc/manual/generated/out $(trace-gen) doc/manual/render-manpage.sh \ - --out-no-smarty "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 $^ $^.tmp $@ + --out-no-smarty "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 \ + doc/manual/generated/out/markdown/command-ref/nix-env/$*.md \ + $@ -$(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md +doc/manual/generated/in/nix-store-%.1: doc/manual/generated/out $(trace-gen) doc/manual/render-manpage.sh \ - --out-no-smarty "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 $^ $^.tmp $@ + --out-no-smarty "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 \ + doc/manual/generated/out/markdown/command-ref/nix-store/$*.md \ + $@ -$(d)/%.1: $(d)/src/command-ref/%.md - $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@ +doc/manual/generated/in/%.1: doc/manual/generated/out + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 \ + doc/manual/generated/out/markdown/command-ref/$*.md \ + $@ -$(d)/%.8: $(d)/src/command-ref/%.md - $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@ +doc/manual/generated/in/%.8: doc/manual/generated/out + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 \ + doc/manual/generated/out/markdown/command-ref/$*.md \ + $@ -$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md - $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ +doc/manual/generated/in/nix.conf.5: doc/manual/generated/out + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 \ + doc/manual/generated/out/markdown/command-ref/conf-file.md \ + $@ -$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md - $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ +doc/manual/generated/in/nix-profiles.5: doc/manual/generated/out + $(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 \ + doc/manual/generated/out/markdown/command-ref/files/profiles.md \ + $@ -$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix) +doc/manual/generated/in/command-ref/new-cli: doc/manual/generated/in/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix) + @mkdir -p doc/manual/generated/in/command-ref @rm -rf $@ $@.tmp $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)' @mv $@.tmp $@ -$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(doc_nix) - @cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp - $(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp; - @mv $@.tmp $@ +doc/manual/generated/in/command-ref/conf-file.md: doc/manual/generated/in/conf-file.json $(d)/utils.nix doc/manual/generated/in/command-ref/experimental-features-shortlist.md $(doc_nix) + @mkdir -p doc/manual/generated/in/command-ref + $(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@ -$(d)/nix.json: $(doc_nix) +doc/manual/generated/in/nix.json: $(doc_nix) + @mkdir -p doc/manual/generated/in $(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp @mv $@.tmp $@ -$(d)/conf-file.json: $(doc_nix) +doc/manual/generated/in/conf-file.json: $(doc_nix) + @mkdir -p doc/manual/generated/in $(trace-gen) $(dummy-env) $(doc_nix) show-config --json --experimental-features nix-command > $@.tmp @mv $@.tmp $@ -$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix) +doc/manual/generated/in/contributing/experimental-feature-descriptions.md: doc/manual/generated/in/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix) + @mkdir -p doc/manual/generated/in/contributing @rm -rf $@ $@.tmp $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))' @mv $@.tmp $@ -$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix) +doc/manual/generated/in/command-ref/experimental-features-shortlist.md: doc/manual/generated/in/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix) + @mkdir -p doc/manual/generated/in/command-ref @rm -rf $@ $@.tmp $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))' @mv $@.tmp $@ -$(d)/xp-features.json: $(doc_nix) +doc/manual/generated/in/xp-features.json: $(doc_nix) $(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-xp-features > $@.tmp @mv $@.tmp $@ -$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix) - @cat doc/manual/src/language/builtins-prefix.md > $@.tmp - $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp; - @cat doc/manual/src/language/builtins-suffix.md >> $@.tmp - @mv $@.tmp $@ +doc/manual/generated/in/language/builtins.md: doc/manual/generated/in/language.json $(d)/generate-builtins.nix $(doc_nix) + @mkdir -p doc/manual/generated/in/language + $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@ -$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(doc_nix) - @cat doc/manual/src/language/builtin-constants-prefix.md > $@.tmp - $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@.tmp; - @cat doc/manual/src/language/builtin-constants-suffix.md >> $@.tmp - @mv $@.tmp $@ +doc/manual/generated/in/language/builtin-constants.md: doc/manual/generated/in/language.json $(d)/generate-builtin-constants.nix $(doc_nix) + @mkdir -p doc/manual/generated/in/language + $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@ -$(d)/language.json: $(doc_nix) +doc/manual/generated/in/language.json: $(doc_nix) + @mkdir -p doc/manual/generated/in $(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-language > $@.tmp @mv $@.tmp $@ # Generate "Upcoming release" notes (or clear it and remove from menu) -$(d)/src/release-notes/rl-next-generated.md: $(d)/rl-next $(d)/rl-next/* +doc/manual/generated/in/release-notes/rl-next-generated.md: $(d)/rl-next $(d)/rl-next/* + @mkdir -p doc/manual/generated/in/release-notes @if type -p build-release-notes > /dev/null; then \ echo " GEN " $@; \ build-release-notes doc/manual/rl-next > $@; \ @@ -134,9 +148,9 @@ $(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages @mkdir -p $(DESTDIR)$$(dirname $@) $(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@) -doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli +doc/manual/generated/man1/nix3-manpages: doc/manual/generated/out @mkdir -p $(DESTDIR)$$(dirname $@) - $(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \ + $(trace-gen) for i in doc/manual/generated/out/markdown/command-ref/new-cli/*.md; do \ name=$$(basename $$i .md); \ tmpFile=$$(mktemp); \ if [[ $$name = SUMMARY ]]; then continue; fi; \ @@ -147,11 +161,14 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli done @touch $@ -doc/manual/generated/out: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next-generated.md $(d)/docroot.py +doc/manual/generated/out: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md doc/manual/generated/in/command-ref/new-cli doc/manual/generated/in/command-ref/experimental-features-shortlist.md doc/manual/generated/in/contributing/experimental-feature-descriptions.md doc/manual/generated/in/command-ref/conf-file.md doc/manual/generated/in/language/builtins.md doc/manual/generated/in/language/builtin-constants.md doc/manual/generated/in/release-notes/rl-next-generated.md $(d)/substitute.py @rm -rf $@ $(trace-gen) \ - RUST_LOG=warn mdbook build doc/manual -d generated/out 2>&1 \ + MDBOOK_SUBSTITUTE_SEARCH=doc/manual/generated/in \ + RUST_LOG=warn \ + mdbook build doc/manual -d generated/out 2>&1 \ | { grep -Fv "because fragment resolution isn't implemented" || :; } + @find $@ -iname meson.build -delete $(docdir)/manual/index.html: doc/manual/generated/out @mkdir -p $(DESTDIR)$(docdir) diff --git a/doc/manual/meson.build b/doc/manual/meson.build index 55373d15c..28ff1f587 100644 --- a/doc/manual/meson.build +++ b/doc/manual/meson.build @@ -15,7 +15,7 @@ nix_eval_for_docs_common = nix_for_docs + [ ] nix_eval_for_docs = nix_eval_for_docs_common + '--raw' -nix_conf_file_json = custom_target( +conf_file_json = custom_target( command : nix_for_docs + [ 'show-config', '--json' ], capture : true, output : 'conf-file.json', @@ -30,7 +30,7 @@ nix_conf_file_md_body = custom_target( capture : true, input : [ 'utils.nix', - nix_conf_file_json, + conf_file_json, ], output : 'conf-file.md.body', env : nix_env_for_docs, @@ -40,7 +40,7 @@ nix_conf_file_md = custom_target( command : [ 'cat', '@INPUT@' ], capture : true, input : [ - 'src/command-ref/conf-file-prefix.md', + 'src/command-ref/conf-file.md', nix_conf_file_md_body, ], output : 'conf-file.md', @@ -51,18 +51,81 @@ nix_exp_features_json = custom_target( capture : true, output : 'xp-features.json', ) -nix_exp_feature_shortlist = custom_target( - command : nix_eval_for_docs + [ - '--expr', - 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))', + +language_json = custom_target( + command: [nix, '__dump-language'], + output : 'language.json', + capture : true, + env : nix_env_for_docs, +) + +nix3_cli_json = custom_target( + command : [ nix, '__dump-cli' ], + capture : true, + output : 'nix.json', +) + +generate_manual_deps = files( + 'generate-deps.py', +) + +# Generates builtins.md and builtin-constants.md. +subdir('src/language') +# Generates new-cli pages, experimental-features-shortlist.md, and conf-file.md. +subdir('src/command-ref') +# Generates experimental-feature-descriptions.md. +subdir('src/contributing') +# Generates rl-next-generated.md. +subdir('src/release-notes') + +manual = custom_target( + 'manual', + command : [ + bash, + '-euo', 'pipefail', + '-c', + ''' + @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@ + cd @SOURCE_ROOT@ + @1@ build doc/manual -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; } + rm -rf @2@/manual + mv @2@/html @2@/manual + find @2@/manual -iname meson.build -delete + '''.format( + python.full_path(), + mdbook.full_path(), + meson.current_build_dir(), + ), ], input : [ - 'generate-xp-features-shortlist.nix', - nix_exp_features_json, + generate_manual_deps, + 'book.toml', + 'anchors.jq', + 'custom.css', + nix3_cli_files, + experimental_features_shortlist_md, + experimental_feature_descriptions_md, + conf_file_md, + builtins_md, + builtin_constants_md, + rl_next_generated, ], - output : 'experimental-features-shortlist.md', - capture : true, - env : nix_env_for_docs, + output : [ + 'manual', + 'markdown', + ], + depfile : 'manual.d', + env : { + 'RUST_LOG': 'info', + 'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src', + }, +) +manual_html = manual[0] +manual_md = manual[1] + +install_subdir( + manual_html.full_path(), + install_dir : datadir / 'doc/nix', ) nix_nested_manpages = [ @@ -109,17 +172,20 @@ nix_nested_manpages = [ foreach command : nix_nested_manpages foreach page : command[1] + title = command[0] + ' --' + page + section = '1' custom_target( command : [ './render-manpage.sh', '--out-no-smarty', - command[0] + ' --' + page, - '1', - '@INPUT@', - '@OUTPUT@.tmp', - '@OUTPUT@', + title, + section, + '@INPUT0@/command-ref' / command[0] / (page + '.md'), + '@OUTPUT0@', + ], + input : [ + manual_md, ], - input : 'src/command-ref' / command[0] / (page + '.md'), output : command[0] + '-' + page + '.1', install : true, install_dir : mandir / 'man1', @@ -127,43 +193,6 @@ foreach command : nix_nested_manpages endforeach endforeach -nix3_cli_json = custom_target( - command : [ nix, '__dump-cli' ], - capture : true, - output : 'nix.json', -) - -# Intermediate step for manpage generation. -# This splorks the output of generate-manpage.nix as JSON, -# which gets written as a directory tree below. -nix3_cli_files_json = custom_target( - command : nix_eval_for_docs_common + [ - '--json', - '--expr', - 'import @INPUT0@ true (builtins.readFile @INPUT1@)', - ], - input : [ - 'generate-manpage.nix', - nix3_cli_json, - ], - capture : true, - output : 'new-cli.json', - env : nix_env_for_docs, -) -nix3_cli_files = custom_target( - command : [ - python, - '@INPUT0@', - '-i', '@INPUT1@', - '-o', '@OUTPUT@', - ], - input : [ - 'json-to-tree.py', - nix3_cli_files_json, - ], - output : 'new-cli', -) - nix3_manpages = [ 'nix3-build', 'nix3-bundle', @@ -254,16 +283,20 @@ nix3_manpages = [ ] foreach page : nix3_manpages + section = '1' custom_target( command : [ - './render-manpage.sh', + bash, + '@INPUT0@', page, - '1', - '@INPUT0@/' + page + '.md', - '@OUTPUT@.tmp', + section, + '@INPUT1@/command-ref/new-cli/@0@.md'.format(page), '@OUTPUT@', ], - input : nix3_cli_files, + input : [ + 'render-manpage.sh', + manual_md, + ], output : page + '.1', install : true, install_dir : mandir / 'man1', @@ -281,24 +314,30 @@ nix_manpages = [ [ 'nix-channel', 1 ], [ 'nix-hash', 1 ], [ 'nix-copy-closure', 1 ], - [ 'nix.conf', 5, nix_conf_file_md, nix_exp_feature_shortlist ], + [ 'nix.conf', 5, 'conf-file.md' ], [ 'nix-daemon', 8 ], - [ 'nix-profiles', 5, 'src/command-ref/files/profiles.md', nix_exp_feature_shortlist ], + [ 'nix-profiles', 5, 'files/profiles.md' ], ] foreach entry : nix_manpages + title = entry[0] + # nix.conf.5 and nix-profiles.5 are based off of conf-file.md and files/profiles.md, + # rather than a stem identical to its mdbook source. + # Therefore we use an optional third element of this array to override the name pattern + md_file = entry.get(2, title + '.md') + section = entry[1].to_string() custom_target( command : [ - './render-manpage.sh', - entry[0], - entry[1].to_string(), + bash, '@INPUT0@', - '@OUTPUT@.tmp', + title, + section, + '@INPUT1@/command-ref/@0@'.format(md_file), '@OUTPUT@', - meson.current_build_dir(), ], input : [ - entry.get(2, 'src/command-ref' / (entry[0] + '.md')), + 'render-manpage.sh', + manual_md, entry.get(3, []), ], output : '@0@.@1@'.format(entry[0], entry[1]), diff --git a/doc/manual/render-manpage.sh b/doc/manual/render-manpage.sh index 42f13911e..7d83253cb 100755 --- a/doc/manual/render-manpage.sh +++ b/doc/manual/render-manpage.sh @@ -9,14 +9,17 @@ if [ "$1" = --out-no-smarty ]; then shift fi +[ "$#" = 4 ] || { + echo "wrong number of args passed" >&2 + exit 1 +} + title="$1" section="$2" infile="$3" -tmpfile="$4" -outfile="$5" +outfile="$4" -printf "Title: %s\n\n" "$title" > "$tmpfile" -cat "$infile" >> "$tmpfile" -"$(dirname "$0")"/process-includes.sh "$infile" "$tmpfile" -lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" "$tmpfile" -o "$outfile" -rm "$tmpfile" +( + printf "Title: %s\n\n" "$title" + cat "$infile" +) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile" diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md deleted file mode 100644 index 822777eff..000000000 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ /dev/null @@ -1,69 +0,0 @@ -# Name - -`nix.conf` - Nix configuration file - -# Description - -Nix supports a variety of configuration settings, which are read from configuration files or taken as command line flags. - -## Configuration file - -By default Nix reads settings from the following places, in that order: - -1. The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. - - Values loaded in this file are not forwarded to the Nix daemon. - The client assumes that the daemon has already loaded them. - -1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order. - - Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and `XDG_CONFIG_HOME`. - If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). - -1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. - -### File format - -Configuration files consist of `name = value` pairs, one per line. -Comments start with a `#` character. - -Example: - -``` -keep-outputs = true # Nice for developers -keep-derivations = true # Idem -``` - -Other files can be included with a line like `include `, where `` is interpreted relative to the current configuration file. -A missing file is an error unless `!include` is used instead. - -A configuration setting usually overrides any previous value. -However, for settings that take a list of items, you can prefix the name of the setting by `extra-` to *append* to the previous value. - -For instance, - -``` -substituters = a b -extra-substituters = c d -``` - -defines the `substituters` setting to be `a b c d`. - -Unknown option names are not an error, and are simply ignored with a warning. - -## Command line flags - -Configuration options can be set on the command line, overriding the values set in the [configuration file](#configuration-file): - -- Every configuration setting has corresponding command line flag (e.g. `--max-jobs 16`). - Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`). - - Unknown option names are invalid flags (unless there is already a flag with that name), and are rejected with an error. - -- The flag `--option ` is interpreted exactly like a ` = ` in a setting file. - - Unknown option names are ignored with a warning. - -The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`). - -# Available settings diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md new file mode 100644 index 000000000..980cf8c14 --- /dev/null +++ b/doc/manual/src/command-ref/conf-file.md @@ -0,0 +1,71 @@ +# Name + +`nix.conf` - Nix configuration file + +# Description + +Nix supports a variety of configuration settings, which are read from configuration files or taken as command line flags. + +## Configuration file + +By default Nix reads settings from the following places, in that order: + +1. The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e. `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if [`NIX_CONF_DIR`](./env-common.md#env-NIX_CONF_DIR) is set. + + Values loaded in this file are not forwarded to the Nix daemon. + The client assumes that the daemon has already loaded them. + +1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order. + + Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and `XDG_CONFIG_HOME`. + If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). + +1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file. + +### File format + +Configuration files consist of `name = value` pairs, one per line. +Comments start with a `#` character. + +Example: + +``` +keep-outputs = true # Nice for developers +keep-derivations = true # Idem +``` + +Other files can be included with a line like `include `, where `` is interpreted relative to the current configuration file. +A missing file is an error unless `!include` is used instead. + +A configuration setting usually overrides any previous value. +However, for settings that take a list of items, you can prefix the name of the setting by `extra-` to *append* to the previous value. + +For instance, + +``` +substituters = a b +extra-substituters = c d +``` + +defines the `substituters` setting to be `a b c d`. + +Unknown option names are not an error, and are simply ignored with a warning. + +## Command line flags + +Configuration options can be set on the command line, overriding the values set in the [configuration file](#configuration-file): + +- Every configuration setting has corresponding command line flag (e.g. `--max-jobs 16`). + Boolean settings do not need an argument, and can be explicitly disabled with the `no-` prefix (e.g. `--keep-failed` and `--no-keep-failed`). + + Unknown option names are invalid flags (unless there is already a flag with that name), and are rejected with an error. + +- The flag `--option ` is interpreted exactly like a ` = ` in a setting file. + + Unknown option names are ignored with a warning. + +The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`). + +# Available settings + +{{#include @generated@/command-ref/conf-file.md}} diff --git a/doc/manual/src/command-ref/meson.build b/doc/manual/src/command-ref/meson.build new file mode 100644 index 000000000..6405ce685 --- /dev/null +++ b/doc/manual/src/command-ref/meson.build @@ -0,0 +1,65 @@ +xp_features_json = custom_target( + command : [nix, '__dump-xp-features'], + capture : true, + output : 'xp-features.json', +) + +experimental_features_shortlist_md = custom_target( + command : nix_eval_for_docs + [ + '--expr', + 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))', + ], + input : [ + '../../generate-xp-features-shortlist.nix', + xp_features_json, + ], + capture : true, + output : 'experimental-features-shortlist.md', + env : nix_env_for_docs, +) + +# Intermediate step for manpage generation. +# This splorks the output of generate-manpage.nix as JSON, +# which gets written as a directory tree below. +nix3_cli_files_json = custom_target( + command : nix_eval_for_docs_common + [ + '--json', + '--expr', + 'import @INPUT0@ true (builtins.readFile @INPUT1@)', + ], + input : [ + '../../generate-manpage.nix', + nix3_cli_json, + ], + capture : true, + output : 'new-cli.json', + env : nix_env_for_docs, +) +nix3_cli_files = custom_target( + command : [ + python, + '@INPUT0@', + '-i', '@INPUT1@', + '-o', '@OUTPUT@', + ], + input : [ + '../../json-to-tree.py', + nix3_cli_files_json, + ], + output : 'new-cli', +) + +conf_file_md = custom_target( + command : [ + nix_eval_for_docs, + '--expr', + '(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))', + ], + capture : true, + input : [ + '../../utils.nix', + conf_file_json, + experimental_features_shortlist_md, + ], + output : 'conf-file.md', +) diff --git a/doc/manual/src/command-ref/new-cli/nix.md b/doc/manual/src/command-ref/new-cli/nix.md new file mode 100644 index 000000000..586800c40 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-build.md b/doc/manual/src/command-ref/new-cli/nix3-build.md new file mode 100644 index 000000000..08d067501 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-build.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-build.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-bundle.md b/doc/manual/src/command-ref/new-cli/nix3-bundle.md new file mode 100644 index 000000000..ebfcca2f4 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-bundle.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-bundle.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-copy.md b/doc/manual/src/command-ref/new-cli/nix3-copy.md new file mode 100644 index 000000000..29fefff59 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-copy.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-copy.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-daemon.md b/doc/manual/src/command-ref/new-cli/nix3-daemon.md new file mode 100644 index 000000000..a0c0fd02e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-daemon.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-daemon.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-derivation-add.md b/doc/manual/src/command-ref/new-cli/nix3-derivation-add.md new file mode 100644 index 000000000..4ec3ff16c --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-derivation-add.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-derivation-add.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-derivation-show.md b/doc/manual/src/command-ref/new-cli/nix3-derivation-show.md new file mode 100644 index 000000000..8cf5dbe0a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-derivation-show.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-derivation-show.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-derivation.md b/doc/manual/src/command-ref/new-cli/nix3-derivation.md new file mode 100644 index 000000000..3a80ebbb5 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-derivation.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-derivation.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-develop.md b/doc/manual/src/command-ref/new-cli/nix3-develop.md new file mode 100644 index 000000000..55cb03987 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-develop.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-develop.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-doctor.md b/doc/manual/src/command-ref/new-cli/nix3-doctor.md new file mode 100644 index 000000000..f6e0b401a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-doctor.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-doctor.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-edit.md b/doc/manual/src/command-ref/new-cli/nix3-edit.md new file mode 100644 index 000000000..a841f2456 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-edit.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-edit.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-eval.md b/doc/manual/src/command-ref/new-cli/nix3-eval.md new file mode 100644 index 000000000..16ac2517e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-eval.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-eval.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-archive.md b/doc/manual/src/command-ref/new-cli/nix3-flake-archive.md new file mode 100644 index 000000000..5e4cdb1b2 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-archive.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-archive.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-check.md b/doc/manual/src/command-ref/new-cli/nix3-flake-check.md new file mode 100644 index 000000000..677c964aa --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-check.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-check.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-clone.md b/doc/manual/src/command-ref/new-cli/nix3-flake-clone.md new file mode 100644 index 000000000..be53e26ce --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-clone.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-clone.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-info.md b/doc/manual/src/command-ref/new-cli/nix3-flake-info.md new file mode 100644 index 000000000..118e09b23 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-info.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-info.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-init.md b/doc/manual/src/command-ref/new-cli/nix3-flake-init.md new file mode 100644 index 000000000..48cc0f3ef --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-init.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-init.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-lock.md b/doc/manual/src/command-ref/new-cli/nix3-flake-lock.md new file mode 100644 index 000000000..9d6845653 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-lock.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-lock.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md b/doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md new file mode 100644 index 000000000..8930bb5e1 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-metadata.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-new.md b/doc/manual/src/command-ref/new-cli/nix3-flake-new.md new file mode 100644 index 000000000..5b7d9ebdf --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-new.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-new.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md b/doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md new file mode 100644 index 000000000..69b41faae --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-prefetch.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-show.md b/doc/manual/src/command-ref/new-cli/nix3-flake-show.md new file mode 100644 index 000000000..59755e960 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-show.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-show.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake-update.md b/doc/manual/src/command-ref/new-cli/nix3-flake-update.md new file mode 100644 index 000000000..f897e504f --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake-update.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake-update.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-flake.md b/doc/manual/src/command-ref/new-cli/nix3-flake.md new file mode 100644 index 000000000..97d38f1bb --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-flake.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-flake.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-fmt.md b/doc/manual/src/command-ref/new-cli/nix3-fmt.md new file mode 100644 index 000000000..ed31de3f7 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-fmt.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-fmt.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-file.md b/doc/manual/src/command-ref/new-cli/nix3-hash-file.md new file mode 100644 index 000000000..b81754594 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-file.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-file.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-path.md b/doc/manual/src/command-ref/new-cli/nix3-hash-path.md new file mode 100644 index 000000000..9928928f2 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-path.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-path.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md new file mode 100644 index 000000000..fb04ccee8 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-to-base16.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md new file mode 100644 index 000000000..2e40c1077 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-to-base32.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md new file mode 100644 index 000000000..8ec8ecbc6 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-to-base64.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md b/doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md new file mode 100644 index 000000000..00298dff0 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash-to-sri.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-hash.md b/doc/manual/src/command-ref/new-cli/nix3-hash.md new file mode 100644 index 000000000..68ab9862e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-hash.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-hash.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-help-stores.md b/doc/manual/src/command-ref/new-cli/nix3-help-stores.md new file mode 100644 index 000000000..f397cc046 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-help-stores.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-help-stores.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-help.md b/doc/manual/src/command-ref/new-cli/nix3-help.md new file mode 100644 index 000000000..306f1ea7a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-help.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-help.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md b/doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md new file mode 100644 index 000000000..9f6e1be3a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-key-convert-secret-to-public.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md b/doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md new file mode 100644 index 000000000..28225d3c8 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-key-generate-secret.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-key.md b/doc/manual/src/command-ref/new-cli/nix3-key.md new file mode 100644 index 000000000..7df72030b --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-key.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-key.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-log.md b/doc/manual/src/command-ref/new-cli/nix3-log.md new file mode 100644 index 000000000..8e590bfde --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-log.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-log.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-nar-cat.md b/doc/manual/src/command-ref/new-cli/nix3-nar-cat.md new file mode 100644 index 000000000..21e137cc5 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-nar-cat.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-nar-cat.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md b/doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md new file mode 100644 index 000000000..39d4a0f8d --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-nar-dump-path.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-nar-ls.md b/doc/manual/src/command-ref/new-cli/nix3-nar-ls.md new file mode 100644 index 000000000..60c75831a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-nar-ls.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-nar-ls.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-nar.md b/doc/manual/src/command-ref/new-cli/nix3-nar.md new file mode 100644 index 000000000..91217904d --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-nar.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-nar.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-path-info.md b/doc/manual/src/command-ref/new-cli/nix3-path-info.md new file mode 100644 index 000000000..8db34e0f1 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-path-info.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-path-info.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md b/doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md new file mode 100644 index 000000000..7754780eb --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-print-dev-env.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md b/doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md new file mode 100644 index 000000000..eba30aa16 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-diff-closures.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-history.md b/doc/manual/src/command-ref/new-cli/nix3-profile-history.md new file mode 100644 index 000000000..85e8afc44 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-history.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-history.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-install.md b/doc/manual/src/command-ref/new-cli/nix3-profile-install.md new file mode 100644 index 000000000..bb530cd9a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-install.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-install.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-list.md b/doc/manual/src/command-ref/new-cli/nix3-profile-list.md new file mode 100644 index 000000000..7f6e7a3fa --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-list.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-list.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-remove.md b/doc/manual/src/command-ref/new-cli/nix3-profile-remove.md new file mode 100644 index 000000000..3651cb086 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-remove.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-remove.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md b/doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md new file mode 100644 index 000000000..9c73cf2f0 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-rollback.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md b/doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md new file mode 100644 index 000000000..1b498cfd0 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-upgrade.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md b/doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md new file mode 100644 index 000000000..662169dbe --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile-wipe-history.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-profile.md b/doc/manual/src/command-ref/new-cli/nix3-profile.md new file mode 100644 index 000000000..c98b611a3 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-profile.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-profile.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-realisation-info.md b/doc/manual/src/command-ref/new-cli/nix3-realisation-info.md new file mode 100644 index 000000000..20d172987 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-realisation-info.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-realisation-info.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-realisation.md b/doc/manual/src/command-ref/new-cli/nix3-realisation.md new file mode 100644 index 000000000..7c176f1c6 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-realisation.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-realisation.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-registry-add.md b/doc/manual/src/command-ref/new-cli/nix3-registry-add.md new file mode 100644 index 000000000..9bb491fb3 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-registry-add.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-registry-add.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-registry-list.md b/doc/manual/src/command-ref/new-cli/nix3-registry-list.md new file mode 100644 index 000000000..42c595eaf --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-registry-list.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-registry-list.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-registry-pin.md b/doc/manual/src/command-ref/new-cli/nix3-registry-pin.md new file mode 100644 index 000000000..256f95cab --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-registry-pin.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-registry-pin.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-registry-remove.md b/doc/manual/src/command-ref/new-cli/nix3-registry-remove.md new file mode 100644 index 000000000..4e2dda4f7 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-registry-remove.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-registry-remove.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-registry.md b/doc/manual/src/command-ref/new-cli/nix3-registry.md new file mode 100644 index 000000000..5551d19b3 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-registry.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-registry.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-repl.md b/doc/manual/src/command-ref/new-cli/nix3-repl.md new file mode 100644 index 000000000..da82694fd --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-repl.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-repl.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-run.md b/doc/manual/src/command-ref/new-cli/nix3-run.md new file mode 100644 index 000000000..1114efd9c --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-run.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-run.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-search.md b/doc/manual/src/command-ref/new-cli/nix3-search.md new file mode 100644 index 000000000..b72a5add5 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-search.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-search.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-shell.md b/doc/manual/src/command-ref/new-cli/nix3-shell.md new file mode 100644 index 000000000..82f0af1e2 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-shell.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-shell.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-show-config.md b/doc/manual/src/command-ref/new-cli/nix3-show-config.md new file mode 100644 index 000000000..060fc065d --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-show-config.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-show-config.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-add-file.md b/doc/manual/src/command-ref/new-cli/nix3-store-add-file.md new file mode 100644 index 000000000..fa30cf660 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-add-file.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-add-file.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-add-path.md b/doc/manual/src/command-ref/new-cli/nix3-store-add-path.md new file mode 100644 index 000000000..88ccd4b51 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-add-path.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-add-path.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-cat.md b/doc/manual/src/command-ref/new-cli/nix3-store-cat.md new file mode 100644 index 000000000..de617fc4e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-cat.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-cat.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-copy-log.md b/doc/manual/src/command-ref/new-cli/nix3-store-copy-log.md new file mode 100644 index 000000000..44998311f --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-copy-log.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-copy-log.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-copy-sigs.md b/doc/manual/src/command-ref/new-cli/nix3-store-copy-sigs.md new file mode 100644 index 000000000..cc03ab44e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-copy-sigs.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-copy-sigs.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-delete.md b/doc/manual/src/command-ref/new-cli/nix3-store-delete.md new file mode 100644 index 000000000..42a05162d --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-delete.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-delete.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-diff-closures.md b/doc/manual/src/command-ref/new-cli/nix3-store-diff-closures.md new file mode 100644 index 000000000..fe6bcd235 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-diff-closures.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-diff-closures.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-dump-path.md b/doc/manual/src/command-ref/new-cli/nix3-store-dump-path.md new file mode 100644 index 000000000..c4f34f450 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-dump-path.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-dump-path.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-gc.md b/doc/manual/src/command-ref/new-cli/nix3-store-gc.md new file mode 100644 index 000000000..da79527ab --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-gc.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-gc.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-ls.md b/doc/manual/src/command-ref/new-cli/nix3-store-ls.md new file mode 100644 index 000000000..fb64bcb21 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-ls.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-ls.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-make-content-addressed.md b/doc/manual/src/command-ref/new-cli/nix3-store-make-content-addressed.md new file mode 100644 index 000000000..0a4b6c93a --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-make-content-addressed.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-make-content-addressed.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-optimise.md b/doc/manual/src/command-ref/new-cli/nix3-store-optimise.md new file mode 100644 index 000000000..cc84844d7 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-optimise.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-optimise.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-path-from-hash-part.md b/doc/manual/src/command-ref/new-cli/nix3-store-path-from-hash-part.md new file mode 100644 index 000000000..c9f4d4f1c --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-path-from-hash-part.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-path-from-hash-part.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-ping.md b/doc/manual/src/command-ref/new-cli/nix3-store-ping.md new file mode 100644 index 000000000..e199e904e --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-ping.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-ping.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-prefetch-file.md b/doc/manual/src/command-ref/new-cli/nix3-store-prefetch-file.md new file mode 100644 index 000000000..c72742413 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-prefetch-file.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-prefetch-file.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-repair.md b/doc/manual/src/command-ref/new-cli/nix3-store-repair.md new file mode 100644 index 000000000..7ad9058d8 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-repair.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-repair.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-sign.md b/doc/manual/src/command-ref/new-cli/nix3-store-sign.md new file mode 100644 index 000000000..ec28f973b --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-sign.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-sign.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store-verify.md b/doc/manual/src/command-ref/new-cli/nix3-store-verify.md new file mode 100644 index 000000000..1d115da04 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store-verify.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store-verify.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-store.md b/doc/manual/src/command-ref/new-cli/nix3-store.md new file mode 100644 index 000000000..1a4c3b350 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-store.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-store.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-upgrade-nix.md b/doc/manual/src/command-ref/new-cli/nix3-upgrade-nix.md new file mode 100644 index 000000000..39f095573 --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-upgrade-nix.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-upgrade-nix.md}} diff --git a/doc/manual/src/command-ref/new-cli/nix3-why-depends.md b/doc/manual/src/command-ref/new-cli/nix3-why-depends.md new file mode 100644 index 000000000..c6629ffcd --- /dev/null +++ b/doc/manual/src/command-ref/new-cli/nix3-why-depends.md @@ -0,0 +1 @@ +{{#include @generated@/command-ref/new-cli/nix3-why-depends.md}} diff --git a/doc/manual/src/contributing/experimental-features.md b/doc/manual/src/contributing/experimental-features.md index ad5cffa91..b2dddeb8e 100644 --- a/doc/manual/src/contributing/experimental-features.md +++ b/doc/manual/src/contributing/experimental-features.md @@ -92,4 +92,4 @@ This means that experimental features and RFCs are orthogonal mechanisms, and ca # Currently available experimental features -{{#include ./experimental-feature-descriptions.md}} +{{#include @generated@/contributing/experimental-feature-descriptions.md}} diff --git a/doc/manual/src/contributing/meson.build b/doc/manual/src/contributing/meson.build new file mode 100644 index 000000000..2929578c8 --- /dev/null +++ b/doc/manual/src/contributing/meson.build @@ -0,0 +1,15 @@ +# Intermediate step for experimental-feature-descriptions.md. +# This splorks the output of generate-xp-features.nix as JSON, +# which gets written as a directory tree below. +experimental_feature_descriptions_md = custom_target( + command : nix_eval_for_docs + [ + '--expr', + 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))', + ], + input : [ + '../../generate-xp-features.nix', + xp_features_json, + ], + capture : true, + output : 'experimental-feature-descriptions.md', +) diff --git a/doc/manual/src/language/builtin-constants-prefix.md b/doc/manual/src/language/builtin-constants-prefix.md deleted file mode 100644 index 50f43006d..000000000 --- a/doc/manual/src/language/builtin-constants-prefix.md +++ /dev/null @@ -1,5 +0,0 @@ -# Built-in Constants - -These constants are built into the Nix language evaluator: - -
diff --git a/doc/manual/src/language/builtin-constants-suffix.md b/doc/manual/src/language/builtin-constants-suffix.md deleted file mode 100644 index a74db2857..000000000 --- a/doc/manual/src/language/builtin-constants-suffix.md +++ /dev/null @@ -1 +0,0 @@ -
diff --git a/doc/manual/src/language/builtin-constants.md b/doc/manual/src/language/builtin-constants.md new file mode 100644 index 000000000..74e87146f --- /dev/null +++ b/doc/manual/src/language/builtin-constants.md @@ -0,0 +1,9 @@ +# Built-in Constants + +These constants are built into the Nix language evaluator: + +
+ +{{#include @generated@/language/builtin-constants.md}} + +
diff --git a/doc/manual/src/language/builtins-prefix.md b/doc/manual/src/language/builtins-prefix.md deleted file mode 100644 index 7b2321466..000000000 --- a/doc/manual/src/language/builtins-prefix.md +++ /dev/null @@ -1,16 +0,0 @@ -# Built-in Functions - -This section lists the functions built into the Nix language evaluator. -All built-in functions are available through the global [`builtins`](./builtin-constants.md#builtins-builtins) constant. - -For convenience, some built-ins can be accessed directly: - -- [`derivation`](#builtins-derivation) -- [`import`](#builtins-import) -- [`abort`](#builtins-abort) -- [`throw`](#builtins-throw) - -
-
derivation attrs
-

derivation is described in - its own section.

diff --git a/doc/manual/src/language/builtins-suffix.md b/doc/manual/src/language/builtins-suffix.md deleted file mode 100644 index a74db2857..000000000 --- a/doc/manual/src/language/builtins-suffix.md +++ /dev/null @@ -1 +0,0 @@ -
diff --git a/doc/manual/src/language/builtins.md b/doc/manual/src/language/builtins.md new file mode 100644 index 000000000..2a3972f05 --- /dev/null +++ b/doc/manual/src/language/builtins.md @@ -0,0 +1,20 @@ +# Built-in Functions + +This section lists the functions built into the Nix language evaluator. +All built-in functions are available through the global [`builtins`](./builtin-constants.md#builtins-builtins) constant. + +For convenience, some built-ins can be accessed directly: + +- [`derivation`](#builtins-derivation) +- [`import`](#builtins-import) +- [`abort`](#builtins-abort) +- [`throw`](#builtins-throw) + +
+
derivation attrs
+

derivation is described in + its own section.

+ +{{#include @generated@/language/builtins.md}} + +
diff --git a/doc/manual/src/language/meson.build b/doc/manual/src/language/meson.build new file mode 100644 index 000000000..bc0d147f3 --- /dev/null +++ b/doc/manual/src/language/meson.build @@ -0,0 +1,27 @@ +builtins_md = custom_target( + command : nix_eval_for_docs + [ + '--expr', + 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).builtins', + ], + capture : true, + input : [ + '../../generate-builtins.nix', + language_json, + ], + output : 'builtins.md', + env : nix_env_for_docs, +) + +builtin_constants_md = custom_target( + command : nix_eval_for_docs + [ + '--expr', + 'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@)).constants', + ], + capture : true, + input : [ + '../../generate-builtin-constants.nix', + language_json, + ], + output : 'builtin-constants.md', + env : nix_env_for_docs, +) diff --git a/doc/manual/src/release-notes/meson.build b/doc/manual/src/release-notes/meson.build new file mode 100644 index 000000000..87e74c248 --- /dev/null +++ b/doc/manual/src/release-notes/meson.build @@ -0,0 +1,20 @@ +rl_next_generated = custom_target( + command : [ + 'bash', + '-c', + ''' + if type -p build-release-notes > /dev/null; then + build-release-notes @CURRENT_SOURCE_DIR@ + fi + @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@ + '''.format( + python.full_path(), + ), + ], + input : [ + generate_manual_deps, + ], + output : 'rl-next-generated.md', + capture : true, + depfile : 'rl-next.d', +) diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md index 35033f7b6..bf4bb194b 100644 --- a/doc/manual/src/release-notes/rl-next.md +++ b/doc/manual/src/release-notes/rl-next.md @@ -1,3 +1,3 @@ # Upcoming release -{{#include rl-next-generated.md}} +{{#include @generated@/release-notes/rl-next-generated.md}} diff --git a/doc/manual/substitute.py b/doc/manual/substitute.py new file mode 100755 index 000000000..18b7bed68 --- /dev/null +++ b/doc/manual/substitute.py @@ -0,0 +1,101 @@ +#!/usr/bin/env python3 + +from pathlib import Path +import json +import os, os.path +import sys + +name = 'substitute.py' + +def log(*args, **kwargs): + kwargs['file'] = sys.stderr + return print(f'{name}:', *args, **kwargs) + +def do_include(content: str, relative_md_path: Path, source_root: Path, search_path: Path): + assert not relative_md_path.is_absolute(), f'{relative_md_path=} from mdbook should be relative' + + md_path_abs = source_root / relative_md_path + var_abs = md_path_abs.parent + assert var_abs.is_dir(), f'supposed directory {var_abs} is not a directory (cwd={os.getcwd()})' + + lines = [] + for l in content.splitlines(keepends=True): + if l.strip().startswith("{{#include "): + requested = l.strip()[11:][:-2] + if requested.startswith("@generated@/"): + included = search_path / Path(requested[12:]) + requested = included.relative_to(search_path) + else: + included = source_root / relative_md_path.parent / requested + requested = included.resolve().relative_to(source_root) + assert included.exists(), f"{requested} not found at {included}" + lines.append(do_include(included.read_text(), requested, source_root, search_path) + "\n") + else: + lines.append(l) + return "".join(lines) + +def recursive_replace(data, book_root, search_path): + match data: + case {'sections': sections}: + return data | dict( + sections = [recursive_replace(section, book_root, search_path) for section in sections], + ) + case {'Chapter': chapter}: + path_to_chapter = Path(chapter['path']) + chapter_content = chapter['content'] + + return data | dict( + Chapter = chapter | dict( + # first process includes. this must happen before docroot processing since + # mdbook does not see these included files, only the final agglomeration. + content = do_include( + chapter_content, + path_to_chapter, + book_root, + search_path + ).replace( + '@docroot@', + ("../" * len(path_to_chapter.parent.parts) or "./")[:-1] + ), + sub_items = [ + recursive_replace(sub_item, book_root, search_path) + for sub_item in chapter['sub_items'] + ], + ), + ) + + case rest: + assert False, f'should have been called on a dict, not {type(rest)=}\n\t{rest=}' + +def main(): + + if len(sys.argv) > 1 and sys.argv[1] == 'supports': + return 0 + + # mdbook communicates with us over stdin and stdout. + # It splorks us a JSON array, the first element describing the context, + # the second element describing the book itself, + # and then expects us to send it the modified book JSON over stdout. + + context, book = json.load(sys.stdin) + + # book_root is the directory where book contents leave (ie, src/) + book_root = Path(context['root']) / context['config']['book']['src'] + + # includes pointing into @generated@ will look here + search_path = Path(os.environ['MDBOOK_SUBSTITUTE_SEARCH']) + + # Find @var@ in all parts of our recursive book structure. + replaced_content = recursive_replace(book, book_root, search_path) + + replaced_content_str = json.dumps(replaced_content) + + # Give mdbook our changes. + print(replaced_content_str) + +try: + sys.exit(main()) +except AssertionError as e: + print(f'{name}: INTERNAL ERROR in mdbook preprocessor', file=sys.stderr) + print(f'this is a bug in {name}', file=sys.stderr) + raise diff --git a/meson.build b/meson.build index 22739a4ab..bc55c64c4 100644 --- a/meson.build +++ b/meson.build @@ -258,6 +258,10 @@ dot = find_program('dot', required : false) pymod = import('python') python = pymod.find_installation('python3') +if enable_docs + mdbook = find_program('mdbook') +endif + # Used to workaround https://github.com/mesonbuild/meson/issues/2320 in src/nix/meson.build. installcmd = find_program('install') diff --git a/src/libutil/config.hh b/src/libutil/config.hh index 01e1239b3..fb433c607 100644 --- a/src/libutil/config.hh +++ b/src/libutil/config.hh @@ -436,7 +436,7 @@ struct ExperimentalFeatureSettings : Config { The following experimental features are available: - {{#include experimental-features-shortlist.md}} + {{#include @generated@/command-ref/experimental-features-shortlist.md}} Experimental features are [further documented in the manual](@docroot@/contributing/experimental-features.md). )"}; -- cgit v1.2.3