put all option docs build flavors on equal footing#147265
Merged
infinisil merged 4 commits intoNixOS:masterfrom Dec 8, 2021
pennae:option-docs-build
Merged
put all option docs build flavors on equal footing#147265infinisil merged 4 commits intoNixOS:masterfrom pennae:option-docs-build
infinisil merged 4 commits intoNixOS:masterfrom
pennae:option-docs-build
Conversation
github-actions
bot
added
6.topic: nixos
ofborg
bot
added
10.rebuild-darwin: 0
Contributor
Author
|
to set a stage for this a little, this is part of an effort to cache most of the options doc build as well. json is much easier to merge than the xml output nix produces, and caching parts of the doc build requires merging options descriptions. the MD and asciidoc changes happened to line up with the need to make json the primary export format for option docs so they ended up converted as well. |
use the json file derivation we already have to also generate the asciidoc and md options docs instead of formatting the options in nix. docbook docs are already produced in derivations. the new script produce the exact same output as the old in-nix generation.
there are no remaining users of sorted option lists except the docbook build, which sorts its input separately.
to do this we must replace derivations with attrsets in make-options-doc, since xml can represent derivations differently from attrset but json cannot. this also given asciidoc and mddoc the ability to handle derivation differently, which they previously didn't have.
infinisil
reviewed
Dec 8, 2021
|
|
||
|
|
||
| <xsl:template match="derivation"> | ||
| <xsl:template match="attrs[attr[@name = '_type' and string[@value = 'derivation']]]"> |
Contributor
Author
There was a problem hiding this comment.
nix xml makes a distinction between derivations and attrsets, but json can't. to get around this we instead format derivations as a _typed special value here, like options and examples are handled already
infinisil
approved these changes
Dec 8, 2021
Member
|
Breaks NixOS with Nix 2.3, see #150623. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation for this change
in #142040 the option docs generation was changed to not sort options.xml in the nix build. in that spirit also stop generating ascii doc and MD doc in nix, and farm that out to scripts too. to make this easier we standardize on options.json as the primary source of options documentation, generating options.xml from options.json when needed. (hopefully docbook will go away soon 🤞)
this may slightly slow down the system build. the optionsDocBook build is definitely impacted, but the full system build seems to not be (or within the noise level of our measurements).
Things done
sandbox = trueset innix.conf? (See Nix manual)nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage./result/bin/)nixos/doc/manual/md-to-db.shto update generated release notes