cafkafk/lix
cafkafk/lix
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

Describe active experimental features in the contributing guide

Browse source 
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.
This commit is contained in:
John Ericson 2023-04-06 12:24:11 -04:00
parent 6c4049b38a
commit bc192a95ef
8 changed files with 43 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -23,7 +23,8 @@ perl/Makefile.config
/doc/manual/src/SUMMARY.md
/doc/manual/src/command-ref/new-cli
/doc/manual/src/command-ref/conf-file.md
/doc/manual/src/command-ref/experimental-features.md
/doc/manual/src/command-ref/experimental-features-shortlist.md
/doc/manual/src/contributing/experimental-features
/doc/manual/src/language/builtins.md
# /scripts/

9
doc/manual/generate-xp-features-shortlist.nix Normal file
View file

@ -0,0 +1,9 @@
with builtins;
with import ./utils.nix;
let
showExperimentalFeature = name: doc:
''
- [`${name}`](@docroot@/contributing/experimental-features/${name}.md)
'';
in xps: indent " " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))

22
doc/manual/generate-xp-features.nix
View file

@ -1,11 +1,21 @@
xps:
with builtins;
with import ./utils.nix;
let
showExperimentalFeature = name: doc:
squash ''
- <span id="xp-feature-${name}">[`${name}`](#xp-feature-${name})</span>
makePage = { name, value }:
{
name = "${name}.md";
inherit value;
feature = name;
};
${indent " " doc}
'';
in xps: indent " " (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))
featurePages = map makePage (attrsToList xps);
tableOfContents = let
showEntry = page:
" - [${page.feature}](contributing/experimental-features/${page.name})";
in concatStringsSep "\n" (map showEntry featurePages) + "\n";
in (listToAttrs featurePages) // { "SUMMARY.md" = tableOfContents; }

14
doc/manual/local.mk
View file

@ -81,10 +81,11 @@ $(d)/%.8: $(d)/src/command-ref/%.md
$(d)/nix.conf.5: $(d)/src/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)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-features
@cp $< $@
@$(call process-includes,$@,$@)
@ -93,7 +94,7 @@ $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)'
@mv $@.tmp $@
$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features.md $(bindir)/nix
$(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
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@mv $@.tmp $@
@ -106,11 +107,16 @@ $(d)/conf-file.json: $(bindir)/nix
$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
@mv $@.tmp $@
$(d)/src/command-ref/experimental-features.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(bindir)/nix
$(d)/src/contributing/experimental-features: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(bindir)/nix
@rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
@mv $@.tmp $@
$(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 $@
$(d)/xp-features.json: $(bindir)/nix
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-xp-features > $@.tmp
@mv $@.tmp $@
@ -154,7 +160,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
done
@touch $@
$(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/command-ref/conf-file.md $(d)/src/language/builtins.md
$(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-features $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md
$(trace-gen) \
tmp="$$(mktemp -d)"; \
cp -r doc/manual "$$tmp"; \

1
doc/manual/src/SUMMARY.md.in
View file

@ -96,6 +96,7 @@
- [Contributing](contributing/contributing.md)
- [Hacking](contributing/hacking.md)
- [Experimental Features](contributing/experimental-features.md)
{{#include ./contributing/experimental-features/SUMMARY.md}}
- [CLI guideline](contributing/cli-guideline.md)
- [Release Notes](release-notes/release-notes.md)
- [Release X.Y (202?-??-??)](release-notes/rl-next.md)

3
doc/manual/utils.nix
View file

@ -5,6 +5,9 @@ rec {
concatStrings = concatStringsSep "";
attrsToList = a:
map (name: { inherit name; value = a.${name}; }) (builtins.attrNames a);
replaceStringsRec = from: to: string:
# recursively replace occurrences of `from` with `to` within `string`
# example:

2
src/libutil/config.hh
View file

@ -384,7 +384,7 @@ struct ExperimentalFeatureSettings : Config {
Experimental features available:
{{#include experimental-features.md}}
{{#include experimental-features-shortlist.md}}
Experimental features are [further documented](@docroot@/contributing/experimental-features.md) in the contribution guide.
)"};

2
src/libutil/experimental-features.cc
View file

@ -57,7 +57,7 @@ constexpr std::array<ExperimentalFeatureDetails, 11> xpFeatureDetails = {{
.name = "flakes",
.description = R"(
Enable flakes. See the manual entry for [`nix
flake`](../command-ref/new-cli/nix3-flake.md) for details.
flake`](@docroot@/command-ref/new-cli/nix3-flake.md) for details.
)",
},
{