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.
This commit is contained in:
John Ericson 2023-04-04 22:57:11 -04:00
parent 3f98353f19
commit 53d0836347
8 changed files with 55 additions and 37 deletions

2
.gitignore vendored
View file

@ -19,9 +19,11 @@ perl/Makefile.config
/doc/manual/nix.json /doc/manual/nix.json
/doc/manual/conf-file.json /doc/manual/conf-file.json
/doc/manual/builtins.json /doc/manual/builtins.json
/doc/manual/xp-features.json
/doc/manual/src/SUMMARY.md /doc/manual/src/SUMMARY.md
/doc/manual/src/command-ref/new-cli /doc/manual/src/command-ref/new-cli
/doc/manual/src/command-ref/conf-file.md /doc/manual/src/command-ref/conf-file.md
/doc/manual/src/command-ref/experimental-features.md
/doc/manual/src/language/builtins.md /doc/manual/src/language/builtins.md
# /scripts/ # /scripts/

View file

@ -0,0 +1,11 @@
with builtins;
with import ./utils.nix;
let
showExperimentalFeature = name: doc:
squash ''
- <span id="xp-feature-${name}">[`${name}`](#xp-feature-${name})</span>
${indent " " doc}
'';
in xps: indent " " (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))

View file

@ -88,12 +88,12 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
@cp $< $@ @cp $< $@
@$(call process-includes,$@,$@) @$(call process-includes,$@,$@)
$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(bindir)/nix
@rm -rf $@ $@.tmp @rm -rf $@ $@.tmp
$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)' $(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)'
@mv $@.tmp $@ @mv $@.tmp $@
$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.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.md $(bindir)/nix
@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp @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; $(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
@mv $@.tmp $@ @mv $@.tmp $@
@ -106,6 +106,15 @@ $(d)/conf-file.json: $(bindir)/nix
$(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp $(trace-gen) $(dummy-env) $(bindir)/nix show-config --json --experimental-features nix-command > $@.tmp
@mv $@.tmp $@ @mv $@.tmp $@
$(d)/src/command-ref/experimental-features.md: $(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)/xp-features.json: $(bindir)/nix
$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(bindir)/nix __dump-xp-features > $@.tmp
@mv $@.tmp $@
$(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix $(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix
@cat doc/manual/src/language/builtins-prefix.md > $@.tmp @cat doc/manual/src/language/builtins-prefix.md > $@.tmp
$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp; $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;

View file

@ -74,10 +74,10 @@ rec {
if aliases == [] then "" else if aliases == [] then "" else
"**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}"; "**Deprecated alias:** ${(concatStringsSep ", " (map (s: "`${s}`") aliases))}";
indent = prefix: s:
concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
in result; in result;
indent = prefix: s:
concatStringsSep "\n" (map (x: if x == "" then x else "${prefix}${x}") (splitLines s));
showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo)); showSettings = args: settingsInfo: concatStrings (attrValues (mapAttrs (showSetting args) settingsInfo));
} }

View file

@ -371,8 +371,21 @@ extern GlobalConfig globalConfig;
struct ExperimentalFeatureSettings : Config { struct ExperimentalFeatureSettings : Config {
Setting<std::set<ExperimentalFeature>> experimentalFeatures{this, {}, "experimental-features", Setting<std::set<ExperimentalFeature>> experimentalFeatures{
getExperimentalFeaturesList()}; this, {}, "experimental-features",
R"(
Experimental features that are enabled.
Example:
```
experimental-features = nix-command flakes
```
Experimental features available:
{{#include experimental-features.md}}
)"};
/** /**
* Check whether the given experimental feature is enabled. * Check whether the given experimental feature is enabled.

View file

@ -140,32 +140,12 @@ std::string_view showExperimentalFeature(const ExperimentalFeature tag)
return xpFeatureDetails[(size_t)tag].name; return xpFeatureDetails[(size_t)tag].name;
} }
std::string getExperimentalFeaturesList() { nlohmann::json documentExperimentalFeatures() {
std::string experimentalFeaturesList = R"( StringMap res;
Experimental features that can be enabled. for (auto & xpFeature : xpFeatureDetails)
res[std::string { xpFeature.name }] =
Example: trim(stripIndentation(xpFeature.description));
return (nlohmann::json) res;
```
experimental-features = nix-command flakes
Experimental features available:
)";
for (auto & xpFeature : xpFeatureDetails) {
experimentalFeaturesList += std::string {}
/* length of this first string must be 12, matching the indent of
the descriptions in the xpFeatureDetails literal. FIXME compute
markdown in a less hacky way. */
+ " - "
+ "`" + xpFeature.name + "`"
+ "\n"
+ xpFeature.description
+ "\n\n";
}
return experimentalFeaturesList;
} }
std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> & rawFeatures) std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> & rawFeatures)

View file

@ -51,11 +51,9 @@ std::string_view showExperimentalFeature(const ExperimentalFeature);
/** /**
* Compute the documentation of all experimental features. * Compute the documentation of all experimental features.
* *
* This a markdown bulleted list where each item is first (a) the * See `doc/manual` for how this information is used.
* experimental feature flag name in backticks, and then (b) the
* description of the experimental feature.
*/ */
std::string getExperimentalFeaturesList(); nlohmann::json documentExperimentalFeatures();
/** /**
* Shorthand for `str << showExperimentalFeature(feature)`. * Shorthand for `str << showExperimentalFeature(feature)`.

View file

@ -374,6 +374,11 @@ void mainWrapped(int argc, char * * argv)
return; return;
} }
if (argc == 2 && std::string(argv[1]) == "__dump-xp-features") {
logger->cout(documentExperimentalFeatures().dump());
return;
}
Finally printCompletions([&]() Finally printCompletions([&]()
{ {
if (completions) { if (completions) {