2016-09-20 14:31:23 +00:00
|
|
|
ifeq ($(doc_generate),yes)
|
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
# The version of Nix used to generate the doc. Can also be
|
|
|
|
# `$(nix_INSTALL_PATH)` or just `nix` (to grap ambient from the `PATH`),
|
|
|
|
# if one prefers.
|
|
|
|
doc_nix = $(nix_PATH)
|
|
|
|
|
2020-11-24 13:38:12 +00:00
|
|
|
MANUAL_SRCS := \
|
2023-03-01 10:01:23 +00:00
|
|
|
$(call rwildcard, $(d)/src, *.md) \
|
|
|
|
$(call rwildcard, $(d)/src, */*.md)
|
2020-11-24 13:38:12 +00:00
|
|
|
|
2014-02-01 10:30:21 +00:00
|
|
|
man-pages := $(foreach n, \
|
2023-03-01 10:01:23 +00:00
|
|
|
nix-env.1 nix-store.1 \
|
|
|
|
nix-build.1 nix-shell.1 nix-instantiate.1 \
|
|
|
|
nix-collect-garbage.1 \
|
|
|
|
nix-prefetch-url.1 nix-channel.1 \
|
|
|
|
nix-hash.1 nix-copy-closure.1 \
|
|
|
|
nix.conf.5 nix-daemon.8 \
|
2023-04-27 09:56:52 +00:00
|
|
|
nix-profiles.5 \
|
2023-03-01 10:01:23 +00:00
|
|
|
, $(d)/$(n))
|
2014-09-16 13:29:55 +00:00
|
|
|
|
2023-03-23 15:27:41 +00:00
|
|
|
# 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)))))
|
|
|
|
|
2014-02-01 11:23:14 +00:00
|
|
|
clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
|
2014-02-01 10:30:21 +00:00
|
|
|
|
2020-11-23 16:40:17 +00:00
|
|
|
# Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox.
|
2023-11-27 18:41:30 +00:00
|
|
|
# Set cores to 0 because otherwise `nix config show` resolves the cores based on the current machine
|
2020-11-23 16:40:17 +00:00
|
|
|
dummy-env = env -i \
|
|
|
|
HOME=/dummy \
|
|
|
|
NIX_CONF_DIR=/dummy \
|
|
|
|
NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt \
|
2021-11-26 15:55:43 +00:00
|
|
|
NIX_STATE_DIR=/dummy \
|
|
|
|
NIX_CONFIG='cores = 0'
|
2020-11-23 16:40:17 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix=doc/manual --store dummy:// --impure --raw
|
2020-09-16 14:56:28 +00:00
|
|
|
|
2023-03-01 10:01:45 +00:00
|
|
|
# re-implement mdBook's include directive to make it usable for terminal output and for proper @docroot@ substitution
|
|
|
|
define process-includes
|
|
|
|
while read -r line; do \
|
2023-03-23 15:26:41 +00:00
|
|
|
set -euo pipefail; \
|
2023-03-30 11:54:30 +00:00
|
|
|
filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
|
2023-03-23 15:26:41 +00:00
|
|
|
test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
|
2023-03-30 11:54:30 +00:00
|
|
|
matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
|
2023-03-23 15:26:41 +00:00
|
|
|
sed -i "/$$matchline/r $$filename" $(2); \
|
2023-03-01 10:01:45 +00:00
|
|
|
sed -i "s/$$matchline//" $(2); \
|
2023-03-03 11:56:23 +00:00
|
|
|
done < <(grep '{{#include' $(1))
|
2023-03-01 10:01:45 +00:00
|
|
|
endef
|
|
|
|
|
2023-03-23 15:27:41 +00:00
|
|
|
$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
|
|
|
|
@printf "Title: %s\n\n" "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" > $^.tmp
|
|
|
|
$(render-subcommand)
|
|
|
|
|
|
|
|
$(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md
|
|
|
|
@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
|
|
|
|
$(render-subcommand)
|
|
|
|
|
|
|
|
# FIXME: there surely is some more deduplication to be achieved here with even darker Make magic
|
|
|
|
define render-subcommand
|
|
|
|
@cat $^ >> $^.tmp
|
|
|
|
@$(call process-includes,$^,$^.tmp)
|
|
|
|
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
|
|
|
|
@# fix up `lowdown`'s automatic escaping of `--`
|
|
|
|
@# https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
|
|
|
|
@sed -i 's/\e\[u2013\]/--/' $@
|
|
|
|
@rm $^.tmp
|
|
|
|
endef
|
|
|
|
|
|
|
|
|
2020-07-23 11:09:30 +00:00
|
|
|
$(d)/%.1: $(d)/src/command-ref/%.md
|
2020-10-08 15:30:40 +00:00
|
|
|
@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
|
|
|
|
@cat $^ >> $^.tmp
|
2023-03-01 10:01:45 +00:00
|
|
|
@$(call process-includes,$^,$^.tmp)
|
2022-12-07 15:20:25 +00:00
|
|
|
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
|
2020-10-08 15:30:40 +00:00
|
|
|
@rm $^.tmp
|
2020-07-23 11:09:30 +00:00
|
|
|
|
|
|
|
$(d)/%.8: $(d)/src/command-ref/%.md
|
2020-10-08 15:30:40 +00:00
|
|
|
@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
|
|
|
|
@cat $^ >> $^.tmp
|
2022-12-07 15:20:25 +00:00
|
|
|
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
|
2020-10-08 15:30:40 +00:00
|
|
|
@rm $^.tmp
|
2014-02-01 10:30:21 +00:00
|
|
|
|
2020-07-23 08:56:15 +00:00
|
|
|
$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
|
2020-10-08 15:30:40 +00:00
|
|
|
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
|
|
|
|
@cat $^ >> $^.tmp
|
2023-04-06 16:24:11 +00:00
|
|
|
@$(call process-includes,$^,$^.tmp)
|
2022-12-07 15:20:25 +00:00
|
|
|
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
|
2020-10-08 15:30:40 +00:00
|
|
|
@rm $^.tmp
|
2020-07-23 08:56:15 +00:00
|
|
|
|
2023-04-27 09:56:52 +00:00
|
|
|
$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
|
2023-02-17 17:57:15 +00:00
|
|
|
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
|
|
|
|
@cat $^ >> $^.tmp
|
|
|
|
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
|
|
|
|
@rm $^.tmp
|
|
|
|
|
2023-11-19 15:08:34 +00:00
|
|
|
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
|
2023-03-01 10:01:45 +00:00
|
|
|
@cp $< $@
|
|
|
|
@$(call process-includes,$@,$@)
|
2020-08-17 17:33:18 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(d)/generate-settings.nix $(d)/generate-store-info.nix $(doc_nix)
|
2023-03-21 11:58:14 +00:00
|
|
|
@rm -rf $@ $@.tmp
|
2023-10-04 23:20:26 +00:00
|
|
|
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
|
2023-01-03 09:09:08 +00:00
|
|
|
@mv $@.tmp $@
|
2020-12-02 22:05:28 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(doc_nix)
|
2020-09-16 14:56:28 +00:00
|
|
|
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
|
2023-10-27 05:30:16 +00:00
|
|
|
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix { prefix = "conf"; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
|
2020-09-16 14:56:28 +00:00
|
|
|
@mv $@.tmp $@
|
2020-08-19 16:28:04 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/nix.json: $(doc_nix)
|
|
|
|
$(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
|
2020-09-16 14:56:28 +00:00
|
|
|
@mv $@.tmp $@
|
2020-08-17 17:33:18 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/conf-file.json: $(doc_nix)
|
|
|
|
$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > $@.tmp
|
2020-09-16 14:56:28 +00:00
|
|
|
@mv $@.tmp $@
|
2020-08-19 16:28:04 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
|
2023-04-05 02:57:11 +00:00
|
|
|
@rm -rf $@ $@.tmp
|
|
|
|
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
|
|
|
|
@mv $@.tmp $@
|
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
|
2023-04-06 16:24:11 +00:00
|
|
|
@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 $@
|
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/xp-features.json: $(doc_nix)
|
|
|
|
$(trace-gen) $(dummy-env) $(doc_nix) __dump-xp-features > $@.tmp
|
2023-04-05 02:57:11 +00:00
|
|
|
@mv $@.tmp $@
|
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix)
|
2022-08-04 09:36:32 +00:00
|
|
|
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
|
2023-05-13 17:52:45 +00:00
|
|
|
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp;
|
2022-08-04 09:36:32 +00:00
|
|
|
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
|
2020-09-16 14:56:28 +00:00
|
|
|
@mv $@.tmp $@
|
2020-08-24 12:49:30 +00:00
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(doc_nix)
|
2023-05-13 17:52:45 +00:00
|
|
|
@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 $@
|
|
|
|
|
2021-08-17 02:26:41 +00:00
|
|
|
$(d)/language.json: $(doc_nix)
|
|
|
|
$(trace-gen) $(dummy-env) $(doc_nix) __dump-language > $@.tmp
|
2020-12-04 13:28:27 +00:00
|
|
|
@mv $@.tmp $@
|
2020-08-24 12:49:30 +00:00
|
|
|
|
2023-11-19 15:08:34 +00:00
|
|
|
# Generate "Upcoming release" notes (or clear it and remove from menu)
|
|
|
|
$(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
|
2023-11-24 14:48:41 +00:00
|
|
|
@if type -p changelog-d > /dev/null; then \
|
|
|
|
echo " GEN " $@; \
|
|
|
|
changelog-d doc/manual/rl-next > $@; \
|
|
|
|
else \
|
|
|
|
echo " NULL " $@; \
|
|
|
|
true > $@; \
|
|
|
|
fi
|
2023-11-19 14:05:21 +00:00
|
|
|
|
2023-11-19 15:08:34 +00:00
|
|
|
$(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
|
|
|
|
$(trace-gen) true
|
|
|
|
@if [ -s $< ]; then \
|
|
|
|
echo ' - [Upcoming release](release-notes/rl-next.md)' > $@; \
|
|
|
|
else \
|
|
|
|
true > $@; \
|
|
|
|
fi
|
|
|
|
|
2020-07-22 18:27:23 +00:00
|
|
|
# Generate the HTML manual.
|
2023-02-13 17:37:35 +00:00
|
|
|
.PHONY: manual-html
|
|
|
|
manual-html: $(docdir)/manual/index.html
|
2020-07-22 18:27:23 +00:00
|
|
|
install: $(docdir)/manual/index.html
|
2014-02-01 10:30:21 +00:00
|
|
|
|
2020-12-02 22:05:28 +00:00
|
|
|
# Generate 'nix' manpages.
|
2021-07-27 11:46:07 +00:00
|
|
|
install: $(mandir)/man1/nix3-manpages
|
|
|
|
man: doc/manual/generated/man1/nix3-manpages
|
|
|
|
all: doc/manual/generated/man1/nix3-manpages
|
|
|
|
|
2023-03-01 10:01:45 +00:00
|
|
|
# FIXME: unify with how the other man pages are generated.
|
|
|
|
# this one works differently and does not use any of the amenities provided by `/mk/lib.mk`.
|
2021-07-27 11:48:19 +00:00
|
|
|
$(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
|
2021-08-28 12:30:14 +00:00
|
|
|
@mkdir -p $(DESTDIR)$$(dirname $@)
|
|
|
|
$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)
|
2021-07-16 12:15:38 +00:00
|
|
|
|
2021-07-27 11:46:07 +00:00
|
|
|
doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
|
2021-08-28 12:30:14 +00:00
|
|
|
@mkdir -p $(DESTDIR)$$(dirname $@)
|
2020-12-04 13:28:27 +00:00
|
|
|
$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
|
2023-03-01 10:01:23 +00:00
|
|
|
name=$$(basename $$i .md); \
|
|
|
|
tmpFile=$$(mktemp); \
|
|
|
|
if [[ $$name = SUMMARY ]]; then continue; fi; \
|
|
|
|
printf "Title: %s\n\n" "$$name" > $$tmpFile; \
|
|
|
|
cat $$i >> $$tmpFile; \
|
|
|
|
lowdown -sT man --nroff-nolinks -M section=1 $$tmpFile -o $(DESTDIR)$$(dirname $@)/$$name.1; \
|
|
|
|
rm $$tmpFile; \
|
2020-12-02 22:05:28 +00:00
|
|
|
done
|
2021-09-22 12:12:31 +00:00
|
|
|
@touch $@
|
2020-12-02 22:05:28 +00:00
|
|
|
|
2023-09-21 00:53:50 +00:00
|
|
|
# the `! -name 'contributing.md'` filter excludes the one place where
|
|
|
|
# `@docroot@` is to be preserved for documenting the mechanism
|
|
|
|
# FIXME: maybe contributing guides should live right next to the code
|
|
|
|
# instead of in the manual
|
2023-11-19 14:05:21 +00:00
|
|
|
$(docdir)/manual/index.html: $(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.md
|
2023-01-03 07:53:29 +00:00
|
|
|
$(trace-gen) \
|
2023-03-01 10:01:45 +00:00
|
|
|
tmp="$$(mktemp -d)"; \
|
|
|
|
cp -r doc/manual "$$tmp"; \
|
|
|
|
find "$$tmp" -name '*.md' | while read -r file; do \
|
|
|
|
$(call process-includes,$$file,$$file); \
|
2023-03-30 11:54:30 +00:00
|
|
|
done; \
|
2023-09-21 00:53:50 +00:00
|
|
|
find "$$tmp" -name '*.md' ! -name 'documentation.md' | while read -r file; do \
|
2023-03-01 10:01:45 +00:00
|
|
|
docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
|
|
|
|
sed -i "s,@docroot@,$$docroot,g" "$$file"; \
|
|
|
|
done; \
|
|
|
|
set -euo pipefail; \
|
|
|
|
RUST_LOG=warn mdbook build "$$tmp/manual" -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
|
|
|
|
| { grep -Fv "because fragment resolution isn't implemented" || :; }; \
|
|
|
|
rm -rf "$$tmp/manual"
|
2023-01-03 10:04:52 +00:00
|
|
|
@rm -rf $(DESTDIR)$(docdir)/manual
|
|
|
|
@mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
|
|
|
|
@rm -rf $(DESTDIR)$(docdir)/manual.tmp
|
2016-09-20 14:31:23 +00:00
|
|
|
|
|
|
|
endif
|