forked from lix-project/lix
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:
parent
3f98353f19
commit
53d0836347
2
.gitignore
vendored
2
.gitignore
vendored
|
@ -19,9 +19,11 @@ perl/Makefile.config
|
|||
/doc/manual/nix.json
|
||||
/doc/manual/conf-file.json
|
||||
/doc/manual/builtins.json
|
||||
/doc/manual/xp-features.json
|
||||
/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/language/builtins.md
|
||||
|
||||
# /scripts/
|
||||
|
|
11
doc/manual/generate-xp-features.nix
Normal file
11
doc/manual/generate-xp-features.nix
Normal 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)))
|
|
@ -88,12 +88,12 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli
|
|||
@cp $< $@
|
||||
@$(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
|
||||
$(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 $(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
|
||||
$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { useAnchors = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.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
|
||||
@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
|
||||
@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;
|
||||
|
|
|
@ -74,10 +74,10 @@ rec {
|
|||
if aliases == [] then "" else
|
||||
"**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;
|
||||
|
||||
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));
|
||||
}
|
||||
|
|
|
@ -371,8 +371,21 @@ extern GlobalConfig globalConfig;
|
|||
|
||||
struct ExperimentalFeatureSettings : Config {
|
||||
|
||||
Setting<std::set<ExperimentalFeature>> experimentalFeatures{this, {}, "experimental-features",
|
||||
getExperimentalFeaturesList()};
|
||||
Setting<std::set<ExperimentalFeature>> experimentalFeatures{
|
||||
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.
|
||||
|
|
|
@ -140,32 +140,12 @@ std::string_view showExperimentalFeature(const ExperimentalFeature tag)
|
|||
return xpFeatureDetails[(size_t)tag].name;
|
||||
}
|
||||
|
||||
std::string getExperimentalFeaturesList() {
|
||||
std::string experimentalFeaturesList = R"(
|
||||
Experimental features that can be enabled.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
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;
|
||||
nlohmann::json documentExperimentalFeatures() {
|
||||
StringMap res;
|
||||
for (auto & xpFeature : xpFeatureDetails)
|
||||
res[std::string { xpFeature.name }] =
|
||||
trim(stripIndentation(xpFeature.description));
|
||||
return (nlohmann::json) res;
|
||||
}
|
||||
|
||||
std::set<ExperimentalFeature> parseFeatures(const std::set<std::string> & rawFeatures)
|
||||
|
|
|
@ -51,11 +51,9 @@ std::string_view showExperimentalFeature(const ExperimentalFeature);
|
|||
/**
|
||||
* Compute the documentation of all experimental features.
|
||||
*
|
||||
* This a markdown bulleted list where each item is first (a) the
|
||||
* experimental feature flag name in backticks, and then (b) the
|
||||
* description of the experimental feature.
|
||||
* See `doc/manual` for how this information is used.
|
||||
*/
|
||||
std::string getExperimentalFeaturesList();
|
||||
nlohmann::json documentExperimentalFeatures();
|
||||
|
||||
/**
|
||||
* Shorthand for `str << showExperimentalFeature(feature)`.
|
||||
|
|
|
@ -374,6 +374,11 @@ void mainWrapped(int argc, char * * argv)
|
|||
return;
|
||||
}
|
||||
|
||||
if (argc == 2 && std::string(argv[1]) == "__dump-xp-features") {
|
||||
logger->cout(documentExperimentalFeatures().dump());
|
||||
return;
|
||||
}
|
||||
|
||||
Finally printCompletions([&]()
|
||||
{
|
||||
if (completions) {
|
||||
|
|
Loading…
Reference in a new issue