qyriad/lix
1
0
Fork 0
forked from lix-project/lix
Code Pull requests Activity
lix/doc/manual/local.mk

179 lines
7.9 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)
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +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)
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 \
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
, doc/manual/generated/in/$(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)), \
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand)))))
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
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
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +00:00
nix-eval = $(dummy-env) $(doc_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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/nix-env-%.1: doc/manual/generated/out
build: extract make "functions" into scripts we'll want to use these for the meson builds, and probably eventually rewrite them in something that isn't plain shell. diffoscope confirms that out/share and doc/share are equal before and after these changes Change-Id: I49aa418fc8615cad86d67328e08c28a7405ec952
2024-03-29 19:06:55 +00:00
$(trace-gen) doc/manual/render-manpage.sh \
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
--out-no-smarty "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 \
doc/manual/generated/out/markdown/command-ref/nix-env/$*.md \
$@
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/nix-store-%.1: doc/manual/generated/out
build: extract make "functions" into scripts we'll want to use these for the meson builds, and probably eventually rewrite them in something that isn't plain shell. diffoscope confirms that out/share and doc/share are equal before and after these changes Change-Id: I49aa418fc8615cad86d67328e08c28a7405ec952
2024-03-29 19:06:55 +00:00
$(trace-gen) doc/manual/render-manpage.sh \
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
--out-no-smarty "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 \
doc/manual/generated/out/markdown/command-ref/nix-store/$*.md \
$@
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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 \
$@
Install all manpages
2020-07-23 11:09:30 +00:00
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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 \
$@
Build/install manual
2014-02-01 10:30:21 +00:00
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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 \
$@
Convert nix.conf manpage
2020-07-23 08:56:15 +00:00
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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 \
$@
Document user files of nix
2023-02-17 17:57:15 +00:00
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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 $<))' >> $@
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/nix.json: $(doc_nix)
@mkdir -p doc/manual/generated/in
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +00:00
$(trace-gen) $(dummy-env) $(doc_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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/conf-file.json: $(doc_nix)
@mkdir -p doc/manual/generated/in
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +00:00
$(trace-gen) $(dummy-env) $(doc_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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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
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 $@
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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
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
@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 $@
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/xp-features.json: $(doc_nix)
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +00:00
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-xp-features > $@.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
@mv $@.tmp $@
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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' >> $@
Generate builtins section of the manual
2020-08-24 12:49:30 +00:00
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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' >> $@
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/language.json: $(doc_nix)
@mkdir -p doc/manual/generated/in
Merge pull request #5145 from fedepell/local_doc_build_5140 Docs build: depend on locally built nix executable and not installed one (cherry picked from commit ca72e3e7e8f69526f028475a7a9b40812da1acdd) === includes changes from (because not doing so removes manpages): Merge pull request #9976 from alois31/restore-manual-pages Restore manual pages (cherry picked from commit d3c1997127e0fc08576e842b2bfe046d8a28d2f4) Change-Id: I685ff16163ac552a1754570c03c992c63a461d50
2024-03-05 20:54:40 +00:00
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_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
Merge pull request #9393 from hercules-ci/changelog-d Automatically compile hand-written release notes with `changelog-d` (cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab) Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
2024-03-04 06:11:19 +00:00
# Generate "Upcoming release" notes (or clear it and remove from menu)
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/in/release-notes/rl-next-generated.md: $(d)/rl-next $(d)/rl-next/*
@mkdir -p doc/manual/generated/in/release-notes
build: replace changelog-d with local script hacking changelog-d to support not just github but also forgejo and gerrit is a lot more complicated than it's worth, even moreso since the entire thing can just as well be done with ~60 lines of python. this new script is also much cheaper to instantiate (being python), so having it enabled in all shells is far less of a hassle. we've also adjusted existing release notes that referenced a gerrit cl to auto-link to the cl in question, making the diff a bit bigger closes https://git.lix.systems/lix-project/lix/issues/176 Change-Id: I8ba7dd0070aad9ba4474401731215fcf5d9d2130
2024-03-26 17:32:25 +00:00
@if type -p build-release-notes > /dev/null; then \
Merge pull request #9393 from hercules-ci/changelog-d Automatically compile hand-written release notes with `changelog-d` (cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab) Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
2024-03-04 06:11:19 +00:00
echo " GEN " $@; \
build: replace changelog-d with local script hacking changelog-d to support not just github but also forgejo and gerrit is a lot more complicated than it's worth, even moreso since the entire thing can just as well be done with ~60 lines of python. this new script is also much cheaper to instantiate (being python), so having it enabled in all shells is far less of a hassle. we've also adjusted existing release notes that referenced a gerrit cl to auto-link to the cl in question, making the diff a bit bigger closes https://git.lix.systems/lix-project/lix/issues/176 Change-Id: I8ba7dd0070aad9ba4474401731215fcf5d9d2130
2024-03-26 17:32:25 +00:00
build-release-notes doc/manual/rl-next > $@; \
Merge pull request #9393 from hercules-ci/changelog-d Automatically compile hand-written release notes with `changelog-d` (cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab) Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
2024-03-04 06:11:19 +00:00
else \
echo " NULL " $@; \
true > $@; \
fi
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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
doc/manual/generated/man1/nix3-manpages: doc/manual/generated/out
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 $@)
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
$(trace-gen) for i in doc/manual/generated/out/markdown/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
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
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
docs: put the manual build into a known tmpdir this isn't strictly necessary, but it'll make it a lot easier to put the generated files used by the autoconf build system in this directory too. doing this now already will make the meson transition a lot easier later Change-Id: I5fb39eade2ff88b6093c9ee436c9e8db793e9448
2024-04-08 15:57:38 +00:00
@rm -rf $@
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) \
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
MDBOOK_SUBSTITUTE_SEARCH=doc/manual/generated/in \
RUST_LOG=warn \
mdbook build doc/manual -d generated/out 2>&1 \
docs: put the manual build into a known tmpdir this isn't strictly necessary, but it'll make it a lot easier to put the generated files used by the autoconf build system in this directory too. doing this now already will make the meson transition a lot easier later Change-Id: I5fb39eade2ff88b6093c9ee436c9e8db793e9448
2024-04-08 15:57:38 +00:00
| { grep -Fv "because fragment resolution isn't implemented" || :; }
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 <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-04-08 19:44:40 +00:00
@find $@ -iname meson.build -delete
docs: put the manual build into a known tmpdir this isn't strictly necessary, but it'll make it a lot easier to put the generated files used by the autoconf build system in this directory too. doing this now already will make the meson transition a lot easier later Change-Id: I5fb39eade2ff88b6093c9ee436c9e8db793e9448
2024-04-08 15:57:38 +00:00
$(docdir)/manual/index.html: doc/manual/generated/out
@mkdir -p $(DESTDIR)$(docdir)
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
docs: put the manual build into a known tmpdir this isn't strictly necessary, but it'll make it a lot easier to put the generated files used by the autoconf build system in this directory too. doing this now already will make the meson transition a lot easier later Change-Id: I5fb39eade2ff88b6093c9ee436c9e8db793e9448
2024-04-08 15:57:38 +00:00
@cp -r $</html $(DESTDIR)$(docdir)/manual
Add a new option to disable documentation generation at configure time
2016-09-20 14:31:23 +00:00
endif
Copy permalink