qyriad/lix
1
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity

docs: redo content generation for mdbook and manual

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

Change-Id: Ia003a3af5b54f2aaa901f8607483a83b73043ac4

<< generate docs bits out of main tree

Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
This commit is contained in:
eldritch horrors 2024-04-08 17:58:10 +02:00
parent c136475a0c
commit 7d37111a6c
99 changed files with 184 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
.gitignore vendored
View file

@ -21,12 +21,8 @@ perl/Makefile.config
/doc/manual/conf-file.json /doc/manual/conf-file.json
/doc/manual/language.json /doc/manual/language.json
/doc/manual/xp-features.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/command-ref/experimental-features-shortlist.md
/doc/manual/src/contributing/experimental-feature-descriptions.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 /doc/manual/src/release-notes/rl-next-generated.md
# /scripts/ # /scripts/

8
doc/manual/book.toml
View file

@ -17,10 +17,18 @@ replace-kind = "relative-to-book-src"
after = ["links"] after = ["links"]
before = ["anchors"] before = ["anchors"]
[preprocessor.generated]
command = "python3 doc/manual/substitute.py generated"
replace-kind = "absolute"
replace-with = "doc/manual/generated/in"
before = ["links"]
[preprocessor.anchors] [preprocessor.anchors]
renderers = ["html"] renderers = ["html"]
command = "jq --from-file doc/manual/anchors.jq" command = "jq --from-file doc/manual/anchors.jq"
[output.markdown]
[output.linkcheck] [output.linkcheck]
# no Internet during the build (in the sandbox) # no Internet during the build (in the sandbox)
follow-web-links = false follow-web-links = false

94
doc/manual/local.mk
View file

@ -17,14 +17,14 @@ man-pages := $(foreach n, \
nix-hash.1 nix-copy-closure.1 \ nix-hash.1 nix-copy-closure.1 \
nix.conf.5 nix-daemon.8 \ nix.conf.5 nix-daemon.8 \
nix-profiles.5 \ nix-profiles.5 \
, $(d)/$(n)) , doc/manual/generated/in/$(n))
# man pages for subcommands # man pages for subcommands
# convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1` # 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 # FIXME: unify with how nix3-cli man pages are generated
man-pages += $(foreach subcommand, \ man-pages += $(foreach subcommand, \
$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/src/command-ref/nix-*/*.md)), \ $(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 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 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 \ $(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 \ $(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 doc/manual/generated/in/%.1: doc/manual/generated/out
$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@ $(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 doc/manual/generated/in/%.8: doc/manual/generated/out
$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@ $(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 doc/manual/generated/in/nix.conf.5: doc/manual/generated/out
$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ $(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 doc/manual/generated/in/nix-profiles.5: doc/manual/generated/out
$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@ $(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 @rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)' $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
@mv $@.tmp $@ @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) 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)
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp @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 $<))' >> $@.tmp; $(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@
@mv $@.tmp $@
$(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 $(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
@mv $@.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 $(trace-gen) $(dummy-env) $(doc_nix) show-config --json --experimental-features nix-command > $@.tmp
@mv $@.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 @rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))' $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
@mv $@.tmp $@ @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 @rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))' $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
@mv $@.tmp $@ @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 $(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-xp-features > $@.tmp
@mv $@.tmp $@ @mv $@.tmp $@
$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix) doc/manual/generated/in/language/builtins.md: doc/manual/generated/in/language.json $(d)/generate-builtins.nix $(doc_nix)
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp @mkdir -p doc/manual/generated/in/language
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp; $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
@mv $@.tmp $@
$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(doc_nix) doc/manual/generated/in/language/builtin-constants.md: doc/manual/generated/in/language.json $(d)/generate-builtin-constants.nix $(doc_nix)
@cat doc/manual/src/language/builtin-constants-prefix.md > $@.tmp @mkdir -p doc/manual/generated/in/language
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@.tmp; $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@
@cat doc/manual/src/language/builtin-constants-suffix.md >> $@.tmp
@mv $@.tmp $@
$(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 $(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-language > $@.tmp
@mv $@.tmp $@ @mv $@.tmp $@
# Generate "Upcoming release" notes (or clear it and remove from menu) # 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 \ @if type -p build-release-notes > /dev/null; then \
echo " GEN " $@; \ echo " GEN " $@; \
build-release-notes doc/manual/rl-next > $@; \ build-release-notes doc/manual/rl-next > $@; \
@ -134,7 +148,7 @@ $(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
@mkdir -p $(DESTDIR)$$(dirname $@) @mkdir -p $(DESTDIR)$$(dirname $@)
$(trace-install) install -m 0644 $$(dirname $<)/* $(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/in/command-ref/new-cli
@mkdir -p $(DESTDIR)$$(dirname $@) @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/src/command-ref/new-cli/*.md; do \
name=$$(basename $$i .md); \ name=$$(basename $$i .md); \
@ -147,7 +161,11 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
done done
@touch $@ @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)/substitute.py # TODO the exp-feature shortlist does not make it into the rendered manual because it's included
# from sources pulled out of cppnix code. the features should probably move into a fresh chapter
# or section and be referenced from the place that currently includes them, or that place should
# reference the full list instead.
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 $@ @rm -rf $@
$(trace-gen) \ $(trace-gen) \
RUST_LOG=warn mdbook build doc/manual -d generated/out 2>&1 \ RUST_LOG=warn mdbook build doc/manual -d generated/out 2>&1 \

18
doc/manual/render-manpage.sh
View file

@ -9,14 +9,18 @@ if [ "$1" = --out-no-smarty ]; then
shift shift
fi fi
[ "$#" = 4 ] || {
echo "wrong number of args passed" >&2
exit 1
}
title="$1" title="$1"
section="$2" section="$2"
infile="$3" infile="$3"
tmpfile="$4" outfile="$4"
outfile="$5"
printf "Title: %s\n\n" "$title" > "$tmpfile" (
cat "$infile" >> "$tmpfile" printf "Title: %s\n\n" "$title"
"$(dirname "$0")"/process-includes.sh "$infile" "$tmpfile" # TODO delete the process-includes script, and possibly this one too
lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" "$tmpfile" -o "$outfile" cat "$infile"
rm "$tmpfile" ) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"

2
doc/manual/src/command-ref/conf-file-prefix.md → doc/manual/src/command-ref/conf-file.md
View file

@ -67,3 +67,5 @@ Configuration options can be set on the command line, overriding the values set
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`). 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 # Available settings
{{#include @generated@/command-ref/conf-file.md}}

1
doc/manual/src/command-ref/new-cli/nix.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix.md}}

1
doc/manual/src/command-ref/new-cli/nix3-build.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-build.md}}

1
doc/manual/src/command-ref/new-cli/nix3-bundle.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-bundle.md}}

1
doc/manual/src/command-ref/new-cli/nix3-copy.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-copy.md}}

1
doc/manual/src/command-ref/new-cli/nix3-daemon.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-daemon.md}}

1
doc/manual/src/command-ref/new-cli/nix3-derivation-add.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-derivation-add.md}}

1
doc/manual/src/command-ref/new-cli/nix3-derivation-show.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-derivation-show.md}}

1
doc/manual/src/command-ref/new-cli/nix3-derivation.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-derivation.md}}

1
doc/manual/src/command-ref/new-cli/nix3-develop.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-develop.md}}

1
doc/manual/src/command-ref/new-cli/nix3-doctor.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-doctor.md}}

1
doc/manual/src/command-ref/new-cli/nix3-edit.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-edit.md}}

1
doc/manual/src/command-ref/new-cli/nix3-eval.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-eval.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-archive.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-archive.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-check.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-check.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-clone.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-clone.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-info.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-info.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-init.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-init.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-lock.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-lock.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-metadata.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-new.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-new.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-prefetch.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-show.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-show.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake-update.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake-update.md}}

1
doc/manual/src/command-ref/new-cli/nix3-flake.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-flake.md}}

1
doc/manual/src/command-ref/new-cli/nix3-fmt.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-fmt.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-file.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-file.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-path.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-path.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-to-base16.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-to-base32.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-to-base64.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash-to-sri.md}}

1
doc/manual/src/command-ref/new-cli/nix3-hash.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-hash.md}}

1
doc/manual/src/command-ref/new-cli/nix3-help-stores.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-help-stores.md}}

1
doc/manual/src/command-ref/new-cli/nix3-help.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-help.md}}

1
doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-key-convert-secret-to-public.md}}

1
doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-key-generate-secret.md}}

1
doc/manual/src/command-ref/new-cli/nix3-key.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-key.md}}

1
doc/manual/src/command-ref/new-cli/nix3-log.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-log.md}}

1
doc/manual/src/command-ref/new-cli/nix3-nar-cat.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-nar-cat.md}}

1
doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-nar-dump-path.md}}

1
doc/manual/src/command-ref/new-cli/nix3-nar-ls.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-nar-ls.md}}

1
doc/manual/src/command-ref/new-cli/nix3-nar.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-nar.md}}

1
doc/manual/src/command-ref/new-cli/nix3-path-info.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-path-info.md}}

1
doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-print-dev-env.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-diff-closures.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-history.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-history.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-install.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-install.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-list.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-list.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-remove.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-remove.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-rollback.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-upgrade.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile-wipe-history.md}}

1
doc/manual/src/command-ref/new-cli/nix3-profile.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-profile.md}}

1
doc/manual/src/command-ref/new-cli/nix3-realisation-info.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-realisation-info.md}}

1
doc/manual/src/command-ref/new-cli/nix3-realisation.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-realisation.md}}

1
doc/manual/src/command-ref/new-cli/nix3-registry-add.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-registry-add.md}}

1
doc/manual/src/command-ref/new-cli/nix3-registry-list.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-registry-list.md}}

1
doc/manual/src/command-ref/new-cli/nix3-registry-pin.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-registry-pin.md}}

1
doc/manual/src/command-ref/new-cli/nix3-registry-remove.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-registry-remove.md}}

1
doc/manual/src/command-ref/new-cli/nix3-registry.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-registry.md}}

1
doc/manual/src/command-ref/new-cli/nix3-repl.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-repl.md}}

1
doc/manual/src/command-ref/new-cli/nix3-run.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-run.md}}

1
doc/manual/src/command-ref/new-cli/nix3-search.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-search.md}}

1
doc/manual/src/command-ref/new-cli/nix3-shell.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-shell.md}}

1
doc/manual/src/command-ref/new-cli/nix3-show-config.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-show-config.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-add-file.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-add-file.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-add-path.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-add-path.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-cat.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-cat.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-copy-log.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-copy-log.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-copy-sigs.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-copy-sigs.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-delete.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-delete.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-diff-closures.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-diff-closures.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-dump-path.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-dump-path.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-gc.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-gc.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-ls.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-ls.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-make-content-addressed.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-make-content-addressed.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-optimise.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-optimise.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-path-from-hash-part.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-path-from-hash-part.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-ping.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-ping.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-prefetch-file.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-prefetch-file.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-repair.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-repair.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-sign.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-sign.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store-verify.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store-verify.md}}

1
doc/manual/src/command-ref/new-cli/nix3-store.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-store.md}}

1
doc/manual/src/command-ref/new-cli/nix3-upgrade-nix.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-upgrade-nix.md}}

1
doc/manual/src/command-ref/new-cli/nix3-why-depends.md Normal file
View file

@ -0,0 +1 @@
{{#include @generated@/command-ref/new-cli/nix3-why-depends.md}}

2
doc/manual/src/contributing/experimental-features.md
View file

@ -92,4 +92,4 @@ This means that experimental features and RFCs are orthogonal mechanisms, and ca
# Currently available experimental features # Currently available experimental features
{{#include ./experimental-feature-descriptions.md}} {{#include @generated@/contributing/experimental-feature-descriptions.md}}

1
doc/manual/src/language/builtin-constants-suffix.md
View file

@ -1 +0,0 @@
</dl>

4
doc/manual/src/language/builtin-constants-prefix.md → doc/manual/src/language/builtin-constants.md
View file

@ -3,3 +3,7 @@
These constants are built into the Nix language evaluator: These constants are built into the Nix language evaluator:
<dl> <dl>
{{#include @generated@/language/builtin-constants.md}}
</dl>

1
doc/manual/src/language/builtins-suffix.md
View file

@ -1 +0,0 @@
</dl>

4
doc/manual/src/language/builtins-prefix.md → doc/manual/src/language/builtins.md
View file

@ -14,3 +14,7 @@ For convenience, some built-ins can be accessed directly:
<dt id="builtins-derivation"><a href="#builtins-derivation"><code>derivation <var>attrs</var></code></a></dt> <dt id="builtins-derivation"><a href="#builtins-derivation"><code>derivation <var>attrs</var></code></a></dt>
<dd><p><var>derivation</var> is described in <dd><p><var>derivation</var> is described in
<a href="derivations.md">its own section</a>.</p></dd> <a href="derivations.md">its own section</a>.</p></dd>
{{#include @generated@/language/builtins.md}}
</dl>

2
doc/manual/src/release-notes/rl-next.md
View file

@ -1,3 +1,3 @@
# Upcoming release # Upcoming release
{{#include rl-next-generated.md}} {{#include @generated@/release-notes/rl-next-generated.md}}

12
doc/manual/substitute.py
View file

@ -13,7 +13,6 @@ def log(*args, **kwargs):
def relative_to(var: str, source_root: Path): def relative_to(var: str, source_root: Path):
def replace(relative_md_path: Path, content: str): def replace(relative_md_path: Path, content: str):
nonlocal source_root
assert not relative_md_path.is_absolute(), f'{relative_md_path=} from mdbook should be relative' assert not relative_md_path.is_absolute(), f'{relative_md_path=} from mdbook should be relative'
md_path_abs = source_root / relative_md_path md_path_abs = source_root / relative_md_path
@ -27,6 +26,12 @@ def relative_to(var: str, source_root: Path):
return replace return replace
def exactly(var: str, value: Path):
def replace(relative_md_path: Path, content: str):
return content.replace(f'@{var}@', value)
return replace
def recursive_replace(data, do_replace): def recursive_replace(data, do_replace):
match data: match data:
case {'sections': sections}: case {'sections': sections}:
@ -72,10 +77,13 @@ def main():
# book_root is the directory where book contents leave (ie, src/) # book_root is the directory where book contents leave (ie, src/)
book_root = Path(context['root']) / context['config']['book']['src'] book_root = Path(context['root']) / context['config']['book']['src']
replace = relative_to(var, book_root) replace = relative_to(var, book_root)
elif config['replace-kind'] == "absolute":
kind = "absolute path " + config['replace-with']
replace = exactly(var, str(Path(config['replace-with']).absolute()))
else: else:
assert False, "need a replace-kind" assert False, "need a replace-kind"
log(f'replacing all occurrences of @{var}@ with a path {kind}') log(f'replacing all occurrences of @{var}@ with {kind}')
# Find @var@ in all parts of our recursive book structure. # Find @var@ in all parts of our recursive book structure.
replaced_content = recursive_replace(book, replace) replaced_content = recursive_replace(book, replace)

2
src/libutil/config.hh
View file

@ -436,7 +436,7 @@ struct ExperimentalFeatureSettings : Config {
The following experimental features are available: 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). Experimental features are [further documented in the manual](@docroot@/contributing/experimental-features.md).
)"}; )"};