lix-project/lix
20
55
Fork 31
Code Issues 344 Code Review (Gerrit) Projects 3 Releases Wiki Activity
lix/doc/manual/local.mk

196 lines
8.3 KiB
Makefile
Raw Normal View History

Add a new option to disable documentation generation at configure time
2016-09-20 14:31:23 +00:00
ifeq ($(doc_generate),yes)
WIP: Document the design of Nix The current docs are all "how to do things" and no "what is Nix" or "why are things the way they are". I see lots of misconception on the wider internet, and I also think we would benefit from a "living document" to answer some questions people currently turn to the thesis for. I think a new section of the manual can address all these issues.
2020-11-24 13:38:12 +00:00
MANUAL_SRCS := \
doc/manual/local.mk: Use tabs instead of spaces everywhere
2023-03-01 10:01:23 +00:00
$(call rwildcard, $(d)/src, *.md) \
$(call rwildcard, $(d)/src, */*.md)
WIP: Document the design of Nix The current docs are all "how to do things" and no "what is Nix" or "why are things the way they are". I see lots of misconception on the wider internet, and I also think we would benefit from a "living document" to answer some questions people currently turn to the thesis for. I think a new section of the manual can address all these issues.
2020-11-24 13:38:12 +00:00
Build/install manual
2014-02-01 10:30:21 +00:00
man-pages := $(foreach n, \
doc/manual/local.mk: Use tabs instead of spaces everywhere
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 \
display documentation on manifest files separately it's probably better not to show the manifest file documentation in the command-specific pages, because these are implementation details that are not really practically useful. this means no additional hassle for building the manual, but clutters the table of contents a bit.
2023-04-27 09:56:52 +00:00
nix-profiles.5 \
doc/manual/local.mk: Use tabs instead of spaces everywhere
2023-03-01 10:01:23 +00:00
, $(d)/$(n))
Fix parallel make of manpages
2014-09-16 13:29:55 +00:00
Split nix-env and nix-store documentation per-subcommand Documentation on "classic" commands with many sub-commands are notoriously hard to discover due to lack of overview and anchor links. Additionally the information on common options and environment variables is not accessible offline in man pages, and therefore often overlooked by readers. With this change, each sub-command of nix-store and nix-env gets its own page in the manual (listed in the table of contents), and each own man page. Also, man pages for each subcommand now (again) list common options and environment variables. While this makes each page quite long and some common parameters don't apply, this should still make it easier to navigate as that additional information was not accessible on the command line at all. It is now possible to run 'nix-store --<subcommand> --help` to display help pages for the given subcommand. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
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)))))
Update Makefile variable names
2014-02-01 11:23:14 +00:00
clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
Build/install manual
2014-02-01 10:30:21 +00:00
Fix macOS sandbox build Since c4c3c15c19bc448a4797e5d9577539cc14890618 (#4251) building Nix for macOS with sandboxing fails: ``` getting status of /nix/var/nix/profiles/per-user/root/channels/nixpkgs: Operation not permitted ``` This happens, because `EvalSettings::getDefaultNixPath` tries to access paths outside the sandbox. Since the state-dir is not required for doc generation, it is set to the dummy folder. This needs to be done for all nix invocations during doc generation, as `EvalSettings::getDefaultNixPath` is called unconditionally.
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.
reproducibility: determinstic man page output for cores
2021-11-26 15:55:43 +00:00
# Set cores to 0 because otherwise nix show-config resolves the cores based on the current machine
Fix macOS sandbox build Since c4c3c15c19bc448a4797e5d9577539cc14890618 (#4251) building Nix for macOS with sandboxing fails: ``` getting status of /nix/var/nix/profiles/per-user/root/channels/nixpkgs: Operation not permitted ``` This happens, because `EvalSettings::getDefaultNixPath` tries to access paths outside the sandbox. Since the state-dir is not required for doc generation, it is set to the dummy folder. This needs to be done for all nix invocations during doc generation, as `EvalSettings::getDefaultNixPath` is called unconditionally.
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 \
reproducibility: determinstic man page output for cores
2021-11-26 15:55:43 +00:00
NIX_STATE_DIR=/dummy \
NIX_CONFIG='cores = 0'
Fix macOS sandbox build Since c4c3c15c19bc448a4797e5d9577539cc14890618 (#4251) building Nix for macOS with sandboxing fails: ``` getting status of /nix/var/nix/profiles/per-user/root/channels/nixpkgs: Operation not permitted ``` This happens, because `EvalSettings::getDefaultNixPath` tries to access paths outside the sandbox. Since the state-dir is not required for doc generation, it is set to the dummy folder. This needs to be done for all nix invocations during doc generation, as `EvalSettings::getDefaultNixPath` is called unconditionally.
2020-11-23 16:40:17 +00:00
Generate separate manpages for each nix subcommand
2020-12-02 22:05:28 +00:00
nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw
Fix doc generation
2020-09-16 14:56:28 +00:00
Documentation: process #include directives
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 \
Manual: fail when #include-d file does not exist
2023-03-23 15:26:41 +00:00
set -euo pipefail; \
process includes first otherwise the order of found `.md` files will influence if `@docroot@` is replaced before them being included, which may mess up relative links. the weirdest thing about it is that the mess-up happens deterministically on macOS, but deterministically doesn't happen on Linux!
2023-03-30 11:54:30 +00:00
filename="$$(dirname $(1))/$$(sed 's/{{#include \(.*\)}}/\1/'<<< $$line)"; \
Manual: fail when #include-d file does not exist
2023-03-23 15:26:41 +00:00
test -f "$$filename" || ( echo "#include-d file '$$filename' does not exist." >&2; exit 1; ); \
process includes first otherwise the order of found `.md` files will influence if `@docroot@` is replaced before them being included, which may mess up relative links. the weirdest thing about it is that the mess-up happens deterministically on macOS, but deterministically doesn't happen on Linux!
2023-03-30 11:54:30 +00:00
matchline="$$(sed 's|/|\\/|g' <<< $$line)"; \
Manual: fail when #include-d file does not exist
2023-03-23 15:26:41 +00:00
sed -i "/$$matchline/r $$filename" $(2); \
Documentation: process #include directives
2023-03-01 10:01:45 +00:00
sed -i "s/$$matchline//" $(2); \
cosmetic indentation Co-authored-by: Théophane Hufschmitt <7226587+thufschmitt@users.noreply.github.com>
2023-03-03 11:56:23 +00:00
done < <(grep '{{#include' $(1))
Documentation: process #include directives
2023-03-01 10:01:45 +00:00
endef
Split nix-env and nix-store documentation per-subcommand Documentation on "classic" commands with many sub-commands are notoriously hard to discover due to lack of overview and anchor links. Additionally the information on common options and environment variables is not accessible offline in man pages, and therefore often overlooked by readers. With this change, each sub-command of nix-store and nix-env gets its own page in the manual (listed in the table of contents), and each own man page. Also, man pages for each subcommand now (again) list common options and environment variables. While this makes each page quite long and some common parameters don't apply, this should still make it easier to navigate as that additional information was not accessible on the command line at all. It is now possible to run 'nix-store --<subcommand> --help` to display help pages for the given subcommand. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
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
Install all manpages
2020-07-23 11:09:30 +00:00
$(d)/%.1: $(d)/src/command-ref/%.md
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
@cat $^ >> $^.tmp
Documentation: process #include directives
2023-03-01 10:01:45 +00:00
@$(call process-includes,$^,$^.tmp)
do not render links in man pages this is a follow-up on e7dcacb. most links are relative and this should not be too much of a detriment.
2022-12-07 15:20:25 +00:00
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@rm $^.tmp
Install all manpages
2020-07-23 11:09:30 +00:00
$(d)/%.8: $(d)/src/command-ref/%.md
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
@cat $^ >> $^.tmp
do not render links in man pages this is a follow-up on e7dcacb. most links are relative and this should not be too much of a detriment.
2022-12-07 15:20:25 +00:00
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@rm $^.tmp
Build/install manual
2014-02-01 10:30:21 +00:00
Convert nix.conf manpage
2020-07-23 08:56:15 +00:00
$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
@cat $^ >> $^.tmp
Describe active experimental features in the contributing guide They are put in the manual separate pages under the new overarching description of experimental features. The settings page just lists the valid experimental feature names (so people know what a valid setting entry looks like), with links to those pages. It doesn't attempt to describe each experimental feature as that is too much information for the configuration settings section.
2023-04-06 16:24:11 +00:00
@$(call process-includes,$^,$^.tmp)
do not render links in man pages this is a follow-up on e7dcacb. most links are relative and this should not be too much of a detriment.
2022-12-07 15:20:25 +00:00
$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
Remove stray 'Title:' from the manual Closes #4096.
2020-10-08 15:30:40 +00:00
@rm $^.tmp
Convert nix.conf manpage
2020-07-23 08:56:15 +00:00
display documentation on manifest files separately it's probably better not to show the manifest file documentation in the command-specific pages, because these are implementation details that are not really practically useful. this means no additional hassle for building the manual, but clutters the table of contents a bit.
2023-04-27 09:56:52 +00:00
$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
Document user files of nix
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
Single page for experimental feature descriptions As requested by @fricklerhandwerk.
2023-04-09 15:01:23 +00:00
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
Documentation: process #include directives
2023-03-01 10:01:45 +00:00
@cp $< $@
@$(call process-includes,$@,$@)
Start generation of the nix.1 manpage
2020-08-17 17:33:18 +00:00
Assemble experimental feature docs outside of Nix itself Instead of constructing a markdown list in C++ (which involved all sorts of nasty string literals), export some JSON and assemble it with the manual build system. Besides following the precedent set with other dumped data, this is a better separate of content and presentation; if we decide for example we want to display this information in a different way, or in a different section of the manual, it will become much easier to do so.
2023-04-05 02:57:11 +00:00
$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(bindir)/nix
nix store --help: Include store type documentation
2023-03-21 11:58:14 +00:00
@rm -rf $@ $@.tmp
backport fix for the `--help` output
2023-11-10 18:22:42 +00:00
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
doc/manual: Introduce @docroot@ as a stable base for includable snippets This way the links are clearly within the manual (ie not absolute paths), while allowing snippets to reference the documentation root reliably, regardless of at which base url they're included.
2023-01-03 09:09:08 +00:00
@mv $@.tmp $@
Generate separate manpages for each nix subcommand
2020-12-02 22:05:28 +00:00
Describe active experimental features in the contributing guide They are put in the manual separate pages under the new overarching description of experimental features. The settings page just lists the valid experimental feature names (so people know what a valid setting entry looks like), with links to those pages. It doesn't attempt to describe each experimental feature as that is too much information for the configuration settings section.
2023-04-06 16:24:11 +00:00
$(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 $(bindir)/nix
Fix doc generation
2020-09-16 14:56:28 +00:00
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
backport fix for the `--help` output
2023-11-10 18:22:42 +00:00
$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
Fix doc generation
2020-09-16 14:56:28 +00:00
@mv $@.tmp $@
Generate the nix.conf docs from the source code This means we don't have two (divergent) sets of option descriptions anymore.
2020-08-19 16:28:04 +00:00
Start generation of the nix.1 manpage
2020-08-17 17:33:18 +00:00
$(d)/nix.json: $(bindir)/nix
nix store --help: Include store type documentation
2023-03-21 11:58:14 +00:00
$(trace-gen) $(dummy-env) $(bindir)/nix __dump-cli > $@.tmp
Fix doc generation
2020-09-16 14:56:28 +00:00
@mv $@.tmp $@
Start generation of the nix.1 manpage
2020-08-17 17:33:18 +00:00
Generate the nix.conf docs from the source code This means we don't have two (divergent) sets of option descriptions anymore.
2020-08-19 16:28:04 +00:00
$(d)/conf-file.json: $(bindir)/nix
Fix macOS sandbox build Since c4c3c15c19bc448a4797e5d9577539cc14890618 (#4251) building Nix for macOS with sandboxing fails: ``` getting status of /nix/var/nix/profiles/per-user/root/channels/nixpkgs: Operation not permitted ``` This happens, because `EvalSettings::getDefaultNixPath` tries to access paths outside the sandbox. Since the state-dir is not required for doc generation, it is set to the dummy folder. This needs to be done for all nix invocations during doc generation, as `EvalSettings::getDefaultNixPath` is called unconditionally.
2020-11-23 16:40:17 +00:00
$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
Fix doc generation
2020-09-16 14:56:28 +00:00
@mv $@.tmp $@
Generate the nix.conf docs from the source code This means we don't have two (divergent) sets of option descriptions anymore.
2020-08-19 16:28:04 +00:00
Single page for experimental feature descriptions As requested by @fricklerhandwerk.
2023-04-09 15:01:23 +00:00
$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(bindir)/nix
Assemble experimental feature docs outside of Nix itself Instead of constructing a markdown list in C++ (which involved all sorts of nasty string literals), export some JSON and assemble it with the manual build system. Besides following the precedent set with other dumped data, this is a better separate of content and presentation; if we decide for example we want to display this information in a different way, or in a different section of the manual, it will become much easier to do so.
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 $@
Describe active experimental features in the contributing guide They are put in the manual separate pages under the new overarching description of experimental features. The settings page just lists the valid experimental feature names (so people know what a valid setting entry looks like), with links to those pages. It doesn't attempt to describe each experimental feature as that is too much information for the configuration settings section.
2023-04-06 16:24:11 +00:00
$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(bindir)/nix
@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 $@
Assemble experimental feature docs outside of Nix itself Instead of constructing a markdown list in C++ (which involved all sorts of nasty string literals), export some JSON and assemble it with the manual build system. Besides following the precedent set with other dumped data, this is a better separate of content and presentation; if we decide for example we want to display this information in a different way, or in a different section of the manual, it will become much easier to do so.
2023-04-05 02:57:11 +00:00
$(d)/xp-features.json: $(bindir)/nix
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-xp-features > $@.tmp
@mv $@.tmp $@
Automatically document builtin constants This is done in roughly the same way builtin functions are documented. Also auto-link experimental features for primops, subsuming PR #8371. Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-05-13 17:52:45 +00:00
$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
manual: remove "Writing Nix Expressions" chapter it is out of date, all over the place in level of detail, is really about `nixpkgs`, and in general instructions should not be part of a reference manual. also: - update redirects and internal links - use "Nix language" consistently
2022-08-04 09:36:32 +00:00
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
Automatically document builtin constants This is done in roughly the same way builtin functions are documented. Also auto-link experimental features for primops, subsuming PR #8371. Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
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;
manual: remove "Writing Nix Expressions" chapter it is out of date, all over the place in level of detail, is really about `nixpkgs`, and in general instructions should not be part of a reference manual. also: - update redirects and internal links - use "Nix language" consistently
2022-08-04 09:36:32 +00:00
@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
Fix doc generation
2020-09-16 14:56:28 +00:00
@mv $@.tmp $@
Generate builtins section of the manual
2020-08-24 12:49:30 +00:00
Automatically document builtin constants This is done in roughly the same way builtin functions are documented. Also auto-link experimental features for primops, subsuming PR #8371. Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-05-13 17:52:45 +00:00
$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(bindir)/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 $@
$(d)/language.json: $(bindir)/nix
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-language > $@.tmp
Make `make install` less noisy Remove the printing and useless output of a couple of commands when running `make install`
2020-12-04 13:28:27 +00:00
@mv $@.tmp $@
Generate builtins section of the manual
2020-08-24 12:49:30 +00:00
Use mdbook
2020-07-22 18:27:23 +00:00
# Generate the HTML manual.
Generate API docs with Doxygen The motivation is as stated in issue #7814: even though the the C++ API is internal and unstable, people still want it to be well documented for sake of learning, code review, and other purposes that aren't predicated on it being stable. Fixes #7814 Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2023-02-13 17:37:35 +00:00
.PHONY: manual-html
manual-html: $(docdir)/manual/index.html
Use mdbook
2020-07-22 18:27:23 +00:00
install: $(docdir)/manual/index.html
Build/install manual
2014-02-01 10:30:21 +00:00
Generate separate manpages for each nix subcommand
2020-12-02 22:05:28 +00:00
# Generate 'nix' manpages.
Fix the generation of nix3 manpages - Separate the generation of the manpages from their installation - Make sure that `make` generates the manpages - Make sure that `make install` installs them Fix #5051
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
Documentation: process #include directives
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`.
Remove dead code in doc’s local.mk
2021-07-27 11:48:19 +00:00
$(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
doc/manual/local.mk: fix 'make install DESTDIR=...' Install failure is observed when we try to install into inplace location as non-root: ``` $ LANG=C make install DESTDIR=$PWD/__i__ V=1 RUST_LOG=warn mdbook build doc/manual -d /usr/share/doc/nix/manual 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Error: Rendering failed 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Caused By: Unexpected error when constructing destination path 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Caused By: Permission denied (os error 13) make: *** [doc/manual/local.mk:98: /usr/share/doc/nix/manual/index.html] Error 101 ``` The change is to prefix paths with `$(DESTDIR)`.
2021-08-28 12:30:14 +00:00
@mkdir -p $(DESTDIR)$$(dirname $@)
$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)
Cleanup the generation of the nix3 manpages Use a dedicated make target for the man page rather than bundling the generation as part of `install`. Also make sure that `make install` is a fixpoint by - Removing the generated markdown files from `MANUAL_SRCS` - Not having the manpage generation write in its source directory so as to not update its timestamp (it would run each time otherwise)
2021-07-16 12:15:38 +00:00
Fix the generation of nix3 manpages - Separate the generation of the manpages from their installation - Make sure that `make` generates the manpages - Make sure that `make install` installs them Fix #5051
2021-07-27 11:46:07 +00:00
doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
doc/manual/local.mk: fix 'make install DESTDIR=...' Install failure is observed when we try to install into inplace location as non-root: ``` $ LANG=C make install DESTDIR=$PWD/__i__ V=1 RUST_LOG=warn mdbook build doc/manual -d /usr/share/doc/nix/manual 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Error: Rendering failed 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Caused By: Unexpected error when constructing destination path 2021-08-28 13:29:58 [ERROR] (mdbook::utils): Caused By: Permission denied (os error 13) make: *** [doc/manual/local.mk:98: /usr/share/doc/nix/manual/index.html] Error 101 ``` The change is to prefix paths with `$(DESTDIR)`.
2021-08-28 12:30:14 +00:00
@mkdir -p $(DESTDIR)$$(dirname $@)
Make `make install` less noisy Remove the printing and useless output of a couple of commands when running `make install`
2020-12-04 13:28:27 +00:00
$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
doc/manual/local.mk: Use tabs instead of spaces everywhere
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; \
Generate separate manpages for each nix subcommand
2020-12-02 22:05:28 +00:00
done
Quiet
2021-09-22 12:12:31 +00:00
@touch $@
Generate separate manpages for each nix subcommand
2020-12-02 22:05:28 +00:00
Automatically document builtin constants This is done in roughly the same way builtin functions are documented. Also auto-link experimental features for primops, subsuming PR #8371. Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-05-13 17:52:45 +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
manual: Check links mdbook-linkcheck is not consistent about its warning setting. It disables some warnings, but not the warnings about lack of fragment checking support; hence the extra filtering.
2023-01-03 07:53:29 +00:00
$(trace-gen) \
Documentation: process #include directives
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); \
process includes first otherwise the order of found `.md` files will influence if `@docroot@` is replaced before them being included, which may mess up relative links. the weirdest thing about it is that the mess-up happens deterministically on macOS, but deterministically doesn't happen on Linux!
2023-03-30 11:54:30 +00:00
done; \
find "$$tmp" -name '*.md' | while read -r file; do \
Documentation: process #include directives
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"
doc/manual: Move the html files back where they were before ... before the link checking "output" was added, bumping the html output into a subdirectory.
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
Add a new option to disable documentation generation at configure time
2016-09-20 14:31:23 +00:00
endif
Reference in a new issue Copy permalink