nordic-dev.net/nixpkgs
nordic-dev.net/nixpkgs
2
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2024-11-22 15:03:28 +00:00
Code Issues Packages Projects Releases Wiki Activity

maintainers: add a helper script for the options doc conversion

Browse Source 
this script can be used to attempt an automatic conversion of option
docs for most modules. it'll also show a diff of options.json before and
after the changes, which should be a good form for checking for unwanted
changes. we specifically show a json diff rather than an xml diff
because newline changes in json are "\n" added are removed, and those
are easier for diff tools to pick out and show in a meaningful way for
this process.

it does *not* check for incorrectly applied changes though, those aren't
easy enough to do automatically for this script.
This commit is contained in:
pennae 2022-06-28 21:29:56 +02:00
parent f2bcc211d7
commit 8e3c7a1fd5
1 changed files with 79 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
maintainers/scripts/mdize-module.sh Executable file
View File

@ -0,0 +1,79 @@
#! /usr/bin/env nix-shell
#! nix-shell -I nixpkgs=. -i bash -p delta jq perl
set -euo pipefail
shopt -s inherit_errexit
cat <<'EOF'
This script attempts to automatically convert option descriptions from
DocBook syntax to markdown. Naturally this process is incomplete and
imperfect, so any changes generated by this script MUST be reviewed.
Possible problems include: incorrectly replaced tags, badly formatted
markdown, DocBook tags this script doesn't recognize remaining in the
output and crashing the docs build, incorrect escaping of markdown
metacharacters, incorrect unescaping of XML entities—and the list goes on.
Always review the generated changes!
EOF
build-options-json() {
nix-build --no-out-link --expr '
let
sys = import ./nixos/default.nix {
configuration = {};
};
in
[
sys.config.system.build.manual.optionsJSON
]
'
}
git diff --quiet || {
echo "Worktree is dirty. Please stash or commit first."
exit 1
}
echo "Building options.json ..."
old_options=$(build-options-json)
echo "Applying replacements ..."
perl -pi -e '
BEGIN {
undef $/;
}
s,<literal>([^`]*?)</literal>,`$1`,smg;
s,<replaceable>([^»]*?)</replaceable>,«$1»,smg;
s,<filename>([^`]*?)</filename>,{file}`$1`,smg;
s,<option>([^`]*?)</option>,{option}`$1`,smg;
s,<code>([^`]*?)</code>,`$1`,smg;
s,<command>([^`]*?)</command>,{command}`$1`,smg;
s,<link xlink:href="(.+?)" ?/>,<$1>,smg;
s,<link xlink:href="(.+?)">(.*?)</link>,[$2]($1),smg;
s,<package>([^`]*?)</package>,`$1`,smg;
s,<emphasis>([^*]*?)</emphasis>,*$1*,smg;
s,<citerefentry>\s*
<refentrytitle>\s*(.*?)\s*</refentrytitle>\s*
<manvolnum>\s*(.*?)\s*</manvolnum>\s*
</citerefentry>,{manpage}`$1($2)`,smgx;
s,^( +description =),\1 lib.mdDoc,smg;
' "$@"
echo "Building options.json again ..."
new_options=$(build-options-json)
! cmp -s {$old_options,$new_options}/share/doc/nixos/options.json && {
diff -U10 \
<(jq . <$old_options/share/doc/nixos/options.json) \
<(jq . <$new_options/share/doc/nixos/options.json) \
| delta
}