Backport #11669 to 2.24-maintenance

.github/ISSUE_TEMPLATE/missing_documentation.md

@@ -23,7 +23,7 @@ assignees: ''
 - [ ] checked [open documentation issues and pull requests] for possible duplicates
 
 [latest Nix manual]: https://nixos.org/manual/nix/unstable/
-[source]: https://github.com/NixOS/nix/tree/master/doc/manual/src
+[source]: https://github.com/NixOS/nix/tree/master/doc/manual/source
 [open documentation issues and pull requests]: https://github.com/NixOS/nix/labels/documentation
 
 ## Priorities

.github/labeler.yml

@@ -9,7 +9,7 @@
     - any-glob-to-any-file: "CONTRIBUTING.md"
     - any-glob-to-any-file: ".github/ISSUE_TEMPLATE/*"
     - any-glob-to-any-file: ".github/PULL_REQUEST_TEMPLATE.md"
-    - any-glob-to-any-file: "doc/manual/src/contributing/**"
+    - any-glob-to-any-file: "doc/manual/source/contributing/**"
 
 "documentation":
   - changed-files:

.gitignore

@@ -23,17 +23,17 @@ perl/Makefile.config
 /doc/manual/conf-file.json
 /doc/manual/language.json
 /doc/manual/xp-features.json
-/doc/manual/src/SUMMARY.md
-/doc/manual/src/SUMMARY-rl-next.md
-/doc/manual/src/store/types/*
-!/doc/manual/src/store/types/index.md.in
-/doc/manual/src/command-ref/new-cli
-/doc/manual/src/command-ref/conf-file.md
-/doc/manual/src/command-ref/experimental-features-shortlist.md
-/doc/manual/src/contributing/experimental-feature-descriptions.md
-/doc/manual/src/language/builtins.md
-/doc/manual/src/language/builtin-constants.md
-/doc/manual/src/release-notes/rl-next.md
+/doc/manual/source/SUMMARY.md
+/doc/manual/source/SUMMARY-rl-next.md
+/doc/manual/source/store/types/*
+!/doc/manual/source/store/types/index.md.in
+/doc/manual/source/command-ref/new-cli
+/doc/manual/source/command-ref/conf-file.md
+/doc/manual/source/command-ref/experimental-features-shortlist.md
+/doc/manual/source/contributing/experimental-feature-descriptions.md
+/doc/manual/source/language/builtins.md
+/doc/manual/source/language/builtin-constants.md
+/doc/manual/source/release-notes/rl-next.md
 
 # /scripts/
 /scripts/nix-profile.sh

CONTRIBUTING.md

@@ -65,7 +65,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
      - Functional tests – [`tests/functional/**.sh`](./tests/functional)
      - Unit tests – [`src/*/tests`](./src/)
      - Integration tests – [`tests/nixos/*`](./tests/nixos)
-   - [ ] User documentation in the [manual](./doc/manual/src)
+   - [ ] User documentation in the [manual](./doc/manual/source)
    - [ ] API documentation in header files
    - [ ] Code and comments are self-explanatory
    - [ ] Commit message explains **why** the change was made
@@ -76,7 +76,7 @@ Check out the [security policy](https://github.com/NixOS/nix/security/policy).
 ## Making changes to the Nix manual
 
 The Nix reference manual is hosted on https://nixos.org/manual/nix.
-The underlying source files are located in [`doc/manual/src`](./doc/manual/src).
+The underlying source files are located in [`doc/manual/source`](./doc/manual/source).
 For small changes you can [use GitHub to edit these files](https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files)
 For larger changes see the [Nix reference manual](https://nix.dev/manual/nix/development/development/contributing.html).
 

doc/manual/book.toml

@@ -1,5 +1,6 @@
 [book]
 title = "Nix Reference Manual"
+src = "source"
 
 [output.html]
 additional-css = ["custom.css"]

doc/manual/generate-store-types.nix

@@ -21,7 +21,7 @@ let
 
   "index.md" = replaceStrings
     [ "@store-types@" ] [ index ]
-    (readFile ./src/store/types/index.md.in);
+    (readFile ./source/store/types/index.md.in);
 
   tableOfContents =
     let

doc/manual/local.mk

@@ -4,8 +4,8 @@
 doc_nix = $(nix_PATH)
 
 MANUAL_SRCS := \
-	$(call rwildcard, $(d)/src, *.md) \
-	$(call rwildcard, $(d)/src, */*.md)
+	$(call rwildcard, $(d)/source, *.md) \
+	$(call rwildcard, $(d)/source, */*.md)
 
 man-pages := $(foreach n, \
 	nix-env.1 nix-store.1 \
@@ -18,11 +18,11 @@ man-pages := $(foreach n, \
 , $(d)/$(n))
 
 # man pages for subcommands
-# convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1`
+# convert from `$(d)/source/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)))))
+	$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/source/command-ref/nix-*/*.md)), \
+	$(d)/$(subst /,-,$(subst $(d)/source/command-ref/,,$(subst .md,.1,$(subcommand)))))
 
 clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8
 
@@ -49,11 +49,11 @@ define process-includes
 	done < <(grep '{{#include' $(1))
 endef
 
-$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
+$(d)/nix-env-%.1: $(d)/source/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
+$(d)/nix-store-%.1: $(d)/source/command-ref/nix-store/%.md
 	@printf -- 'Title: %s\n\n' "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" > $^.tmp
 	$(render-subcommand)
 
@@ -69,50 +69,50 @@ define render-subcommand
 endef
 
 
-$(d)/%.1: $(d)/src/command-ref/%.md
+$(d)/%.1: $(d)/source/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .1)" > $^.tmp
 	@cat $^ >> $^.tmp
 	@$(call process-includes,$^,$^.tmp)
 	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=1 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/%.8: $(d)/src/command-ref/%.md
+$(d)/%.8: $(d)/source/command-ref/%.md
 	@printf "Title: %s\n\n" "$$(basename $@ .8)" > $^.tmp
 	@cat $^ >> $^.tmp
 	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=8 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
+$(d)/nix.conf.5: $(d)/source/command-ref/conf-file.md
 	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
 	@cat $^ >> $^.tmp
 	@$(call process-includes,$^,$^.tmp)
 	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
+$(d)/nix-profiles.5: $(d)/source/command-ref/files/profiles.md
 	@printf "Title: %s\n\n" "$$(basename $@ .5)" > $^.tmp
 	@cat $^ >> $^.tmp
 	$(trace-gen) lowdown -sT man --nroff-nolinks -M section=5 $^.tmp -o $@
 	@rm $^.tmp
 
-$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md
+$(d)/source/SUMMARY.md: $(d)/source/SUMMARY.md.in $(d)/source/SUMMARY-rl-next.md $(d)/source/store/types $(d)/source/command-ref/new-cli $(d)/source/development/experimental-feature-descriptions.md
 	@cp $< $@
 	@$(call process-includes,$@,$@)
 
-$(d)/src/store/types: $(d)/nix.json $(d)/utils.nix $(d)/generate-store-info.nix  $(d)/generate-store-types.nix $(d)/src/store/types/index.md.in $(doc_nix)
+$(d)/source/store/types: $(d)/nix.json $(d)/utils.nix $(d)/generate-store-info.nix  $(d)/generate-store-types.nix $(d)/source/store/types/index.md.in $(doc_nix)
 	@# FIXME: build out of tree!
 	@rm -rf [email protected]
 	$(trace-gen) $(nix-eval) --write-to [email protected] --expr 'import doc/manual/generate-store-types.nix (builtins.fromJSON (builtins.readFile $<)).stores'
 	@# do not destroy existing contents
 	@mv [email protected]/* $@/
 
-$(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)
+$(d)/source/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)
 	@rm -rf $@ [email protected]
 	$(trace-gen) $(nix-eval) --write-to [email protected] --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
 	@mv [email protected] $@
 
-$(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)
-	@cat doc/manual/src/command-ref/conf-file-prefix.md > [email protected]
+$(d)/source/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/generate-settings.nix $(d)/source/command-ref/conf-file-prefix.md $(d)/source/command-ref/experimental-features-shortlist.md $(doc_nix)
+	@cat doc/manual/source/command-ref/conf-file-prefix.md > [email protected]
 	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-settings.nix { prefix = "conf"; } (builtins.fromJSON (builtins.readFile $<))' >> [email protected];
 	@mv [email protected] $@
 
@@ -124,12 +124,12 @@ $(d)/conf-file.json: $(doc_nix)
 	$(trace-gen) $(dummy-env) $(doc_nix) config show --json --experimental-features nix-command > [email protected]
 	@mv [email protected] $@
 
-$(d)/src/development/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
+$(d)/source/development/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
 	@rm -rf $@ [email protected]
 	$(trace-gen) $(nix-eval) --write-to [email protected] --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv [email protected] $@
 
-$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
+$(d)/source/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
 	@rm -rf $@ [email protected]
 	$(trace-gen) $(nix-eval) --write-to [email protected] --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv [email protected] $@
@@ -138,18 +138,18 @@ $(d)/xp-features.json: $(doc_nix)
 	$(trace-gen) $(dummy-env) $(doc_nix) __dump-xp-features > [email protected]
 	@mv [email protected] $@
 
-$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix)
-	@cat doc/manual/src/language/builtins-prefix.md > [email protected]
+$(d)/source/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/source/language/builtins-prefix.md $(doc_nix)
+	@cat doc/manual/source/language/builtins-prefix.md > [email protected]
 	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> [email protected];
-	@cat doc/manual/src/language/builtins-suffix.md >> [email protected]
+	@cat doc/manual/source/language/builtins-suffix.md >> [email protected]
 	@mv [email protected] $@
 
 $(d)/language.json: $(doc_nix)
 	$(trace-gen) $(dummy-env) $(doc_nix) __dump-language > [email protected]
 	@mv [email protected] $@
 
 # Generate "Upcoming release" notes (or clear it and remove from menu)
-$(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
+$(d)/source/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
 	@if type -p changelog-d > /dev/null; then \
 		echo "  GEN   " $@; \
 		changelog-d doc/manual/rl-next > $@; \
@@ -158,7 +158,7 @@ $(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
 		true > $@; \
 	fi
 
-$(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
+$(d)/source/SUMMARY-rl-next.md: $(d)/source/release-notes/rl-next.md
 	$(trace-gen) true
 	@if [ -s $< ]; then \
 		echo '  - [Upcoming release](release-notes/rl-next.md)' > $@; \
@@ -194,9 +194,9 @@ $(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
 	@mkdir -p $(DESTDIR)$$(dirname $@)
 	$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)
 
-doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
+doc/manual/generated/man1/nix3-manpages: $(d)/source/command-ref/new-cli
 	@mkdir -p $(DESTDIR)$$(dirname $@)
-	$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
+	$(trace-gen) for i in doc/manual/source/command-ref/new-cli/*.md; do \
 		name=$$(basename $$i .md); \
 		tmpFile=$$(mktemp); \
 		if [[ $$name = SUMMARY ]]; then continue; fi; \
@@ -211,15 +211,15 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 # `@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
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/store/types $(d)/src/command-ref/new-cli $(d)/src/development/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/release-notes/rl-next.md $(d)/src/figures $(d)/src/favicon.png $(d)/src/favicon.svg
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/source/SUMMARY.md $(d)/source/store/types $(d)/source/command-ref/new-cli $(d)/source/development/experimental-feature-descriptions.md $(d)/source/command-ref/conf-file.md $(d)/source/language/builtins.md $(d)/source/release-notes/rl-next.md $(d)/source/figures $(d)/source/favicon.png $(d)/source/favicon.svg
 	$(trace-gen) \
 		tmp="$$(mktemp -d)"; \
 		cp -r doc/manual "$$tmp"; \
 		find "$$tmp" -name '*.md' | while read -r file; do \
 			$(call process-includes,$$file,$$file); \
 		done; \
 		find "$$tmp" -name '*.md' ! -name 'documentation.md' | while read -r file; do \
-			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
+			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/source)"; \
 			sed -i "s,@docroot@,$$docroot,g" "$$file"; \
 		done; \
 		set -euo pipefail; \

doc/manual/redirects.js

@@ -1,7 +1,7 @@
 // redirect rules for URL fragments (client-side) to prevent link rot.
 // this must be done on the client side, as web servers do not see the fragment part of the URL.
 // it will only work with JavaScript enabled in the browser, but this is the best we can do here.
-// see src/_redirects for path redirects (server-side)
+// see source/_redirects for path redirects (server-side)
 
 // redirects are declared as follows:
 // each entry has as its key a path matching the requested URL path, relative to the mdBook document root.

doc/manual/src/development/documentation.md → doc/manual/source/development/documentation.md

@@ -35,7 +35,7 @@ In order to reflect changes to the [Makefile for the manual], clear all generate
 [Makefile for the manual]: https://github.com/NixOS/nix/blob/master/doc/manual/local.mk
 
 ```console
-rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/src/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
+rm $(git ls-files doc/manual/ -o | grep -F '.md') && rmdir doc/manual/source/command-ref/new-cli && make manual-html -j $NIX_BUILD_CORES
 ```
 
 ## Style guide
@@ -182,7 +182,7 @@ Please observe these guidelines to ease reviews:
 
 `@docroot@` provides a base path for links that occur in reusable snippets or other documentation that doesn't have a base path of its own.
 
-If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/src` directory.
+If a broken link occurs in a snippet that was inserted into multiple generated files in different directories, use `@docroot@` to reference the `doc/manual/source` directory.
 
 If the `@docroot@` literal appears in an error message from the [`mdbook-linkcheck`] tool, the `@docroot@` replacement needs to be applied to the generated source file that mentions it.
 See existing `@docroot@` logic in the [Makefile for the manual].

maintainers/release-notes

@@ -78,7 +78,7 @@ if ! git diff --quiet --cached; then
   die "repo has staged changes, please commit or stash them"
 fi
 
-if ! grep "$SUMMARY_MARKER_LINE" doc/manual/src/SUMMARY.md.in >/dev/null; then
+if ! grep "$SUMMARY_MARKER_LINE" doc/manual/source/SUMMARY.md.in >/dev/null; then
   # would have been nice to catch this early, but won't be worth the extra infra
   die "SUMMARY.md.in is missing the marker line '$SUMMARY_MARKER_LINE', which would be used for inserting a new release notes page. Please fix the script."
 fi
@@ -117,7 +117,7 @@ log "version_full=$version_full"
 log "IS_PATCH=$IS_PATCH"
 
 basename=rl-${version_major_minor}.md
-file=doc/manual/src/release-notes/$basename
+file=doc/manual/source/release-notes/$basename
 
 if ! $IS_PATCH; then
   if [[ -e $file ]]; then
@@ -169,7 +169,7 @@ if ! $IS_PATCH; then
   # find the marker line, insert new link after it
   escaped_marker="$(echo "$SUMMARY_MARKER_LINE" | sed -e 's/\//\\\//g' -e 's/ /\\ /g')"
   escaped_line="$(echo "$NEW_SUMMARY_LINE" | sed -e 's/\//\\\//g' -e 's/ /\\ /g')"
-  logcmd sed -i -e "/$escaped_marker/a $escaped_line" doc/manual/src/SUMMARY.md.in
+  logcmd sed -i -e "/$escaped_marker/a $escaped_line" doc/manual/source/SUMMARY.md.in
 fi
 
 for f in doc/manual/rl-next/*.md; do
@@ -178,7 +178,7 @@ for f in doc/manual/rl-next/*.md; do
   fi
 done
 
-logcmd git add $file doc/manual/src/SUMMARY.md.in
+logcmd git add $file doc/manual/source/SUMMARY.md.in
 logcmd git status
 logcmd git commit -m "release notes: $version_full"
 

src/libstore/unix/build/local-derivation-goal.cc

@@ -3021,7 +3021,7 @@ bool LocalDerivationGoal::isReadDesc(int fd)
 StorePath LocalDerivationGoal::makeFallbackPath(OutputNameView outputName)
 {
     // This is a bogus path type, constructed this way to ensure that it doesn't collide with any other store path
-    // See doc/manual/src/protocols/store-path.md for details
+    // See doc/manual/source/protocols/store-path.md for details
     // TODO: We may want to separate the responsibilities of constructing the path fingerprint and of actually doing the hashing
     auto pathType = "rewrite:" + std::string(drvPath.to_string()) + ":name:" + std::string(outputName);
     return worker.store.makeStorePath(
@@ -3034,7 +3034,7 @@ StorePath LocalDerivationGoal::makeFallbackPath(OutputNameView outputName)
 StorePath LocalDerivationGoal::makeFallbackPath(const StorePath & path)
 {
     // This is a bogus path type, constructed this way to ensure that it doesn't collide with any other store path
-    // See doc/manual/src/protocols/store-path.md for details
+    // See doc/manual/source/protocols/store-path.md for details
     auto pathType = "rewrite:" + std::string(drvPath.to_string()) + ":" + std::string(path.to_string());
     return worker.store.makeStorePath(
         pathType,

src/nix/help-stores.md

@@ -1 +1 @@
-../../doc/manual/src/store/types/index.md.in
+../../doc/manual/source/store/types/index.md.in

src/nix/package.nix

@@ -60,9 +60,9 @@ mkMesonDerivation (finalAttrs: {
     ../nix-env/buildenv.nix
     ./get-env.sh
     ./help-stores.md
-    ../../doc/manual/src/store/types/index.md.in
+    ../../doc/manual/source/store/types/index.md.in
     ./profiles.md
-    ../../doc/manual/src/command-ref/files/profiles.md
+    ../../doc/manual/source/command-ref/files/profiles.md
 
     # Files
   ] ++ lib.concatMap

src/nix/profiles.md

@@ -1 +1 @@
-../../doc/manual/src/command-ref/files/profiles.md
+../../doc/manual/source/command-ref/files/profiles.md

tests/functional/check.sh

@@ -23,7 +23,7 @@ nix-build dependencies.nix --no-out-link
 nix-build dependencies.nix --no-out-link --check
 
 # Build failure exit codes (100, 104, etc.) are from
-# doc/manual/src/command-ref/status-build-failure.md
+# doc/manual/source/command-ref/status-build-failure.md
 
 # check for dangling temporary build directories
 # only retain if build fails and --keep-failed is specified, or...

tests/functional/common/vars-and-functions.sh

@@ -78,7 +78,7 @@ clearProfiles() {
 
 # Clear the store, but do not fail if we're in an environment where we can't.
 # This allows the test to run in a NixOS test environment, where we use the system store.
-# See doc/manual/src/contributing/testing.md / Running functional tests on NixOS.
+# See doc/manual/source/contributing/testing.md / Running functional tests on NixOS.
 clearStoreIfPossible() {
     if isTestOnNixOS; then
         echo "clearStoreIfPossible: Not clearing store, because we're on NixOS. Moving on."