pyrox.dev
Merge pull request #179483 from pennae/mdize-maintainer-script
maintainers: add a helper script for the options doc conversion
+83
maintainers/scripts/mdize-module.sh
+83
maintainers/scripts/mdize-module.sh
···
1
+
#! /usr/bin/env nix-shell
2
+
#! nix-shell -I nixpkgs=. -i bash -p delta jq perl
3
+
4
+
set -euo pipefail
5
+
shopt -s inherit_errexit
6
+
7
+
cat <<'EOF'
8
+
This script attempts to automatically convert option descriptions from
9
+
DocBook syntax to markdown. Naturally this process is incomplete and
10
+
imperfect, so any changes generated by this script MUST be reviewed.
11
+
12
+
Possible problems include: incorrectly replaced tags, badly formatted
13
+
markdown, DocBook tags this script doesn't recognize remaining in the
14
+
output and crashing the docs build, incorrect escaping of markdown
15
+
metacharacters, incorrect unescaping of XML entities—and the list goes on.
16
+
17
+
Always review the generated changes!
18
+
19
+
Some known limitations:
20
+
- Does not transform literalDocBook items
21
+
- Replacements can occur in non-option code, such as string literals
22
+
23
+
24
+
EOF
25
+
26
+
27
+
28
+
build-options-json() {
29
+
nix-build --no-out-link --expr '
30
+
let
31
+
sys = import ./nixos/default.nix {
32
+
configuration = {};
33
+
};
34
+
in
35
+
[
36
+
sys.config.system.build.manual.optionsJSON
37
+
]
38
+
'
39
+
}
40
+
41
+
42
+
43
+
git diff --quiet || {
44
+
echo "Worktree is dirty. Please stash or commit first."
45
+
exit 1
46
+
}
47
+
48
+
echo "Building options.json ..."
49
+
old_options=$(build-options-json)
50
+
51
+
echo "Applying replacements ..."
52
+
perl -pi -e '
53
+
BEGIN {
54
+
undef $/;
55
+
}
56
+
57
+
s,<literal>([^`]*?)</literal>,`$1`,smg;
58
+
s,<replaceable>([^»]*?)</replaceable>,«$1»,smg;
59
+
s,<filename>([^`]*?)</filename>,{file}`$1`,smg;
60
+
s,<option>([^`]*?)</option>,{option}`$1`,smg;
61
+
s,<code>([^`]*?)</code>,`$1`,smg;
62
+
s,<command>([^`]*?)</command>,{command}`$1`,smg;
63
+
s,<link xlink:href="(.+?)" ?/>,<$1>,smg;
64
+
s,<link xlink:href="(.+?)">(.*?)</link>,[$2]($1),smg;
65
+
s,<package>([^`]*?)</package>,`$1`,smg;
66
+
s,<emphasis>([^*]*?)</emphasis>,*$1*,smg;
67
+
s,<citerefentry>\s*
68
+
<refentrytitle>\s*(.*?)\s*</refentrytitle>\s*
69
+
<manvolnum>\s*(.*?)\s*</manvolnum>\s*
70
+
</citerefentry>,{manpage}`$1($2)`,smgx;
71
+
s,^( +description =),\1 lib.mdDoc,smg;
72
+
' "$@"
73
+
74
+
echo "Building options.json again ..."
75
+
new_options=$(build-options-json)
76
+
77
+
78
+
! cmp -s {$old_options,$new_options}/share/doc/nixos/options.json && {
79
+
diff -U10 \
80
+
<(jq . <$old_options/share/doc/nixos/options.json) \
81
+
<(jq . <$new_options/share/doc/nixos/options.json) \
82
+
| delta
83
+
}