Dev: doc/toolchain: implement adocxt (#1374)

extracts sections needed to be generated from argparse help from tags in
crm.8.adoc and generates Makefile for building those adocs

Author: nicholasyang2022

.gitignore

@@ -5,7 +5,7 @@
 doc/website-v1/gen
 Makefile.in
 autom4te.cache
-Makefile
+./Makefile
 aclocal.m4
 autoconf
 autoheader

doc/.gitignore

@@ -0,0 +1 @@
+generated-sources/

doc/Makefile

@@ -0,0 +1,18 @@
+.PHONY: all clean subdirs
+
+all: subdirs generated-sources/crm.8.adoc
+
+generated-sources:
+	mkdir -p $@
+
+generated-sources/Makefile: crm.8.adoc generated-sources
+	adocxt gen-makefile < $< > $@
+
+subdirs: generated-sources/Makefile
+	$(MAKE) -C generated-sources all
+
+generated-sources/crm.8.adoc: crm.8.adoc generated-sources
+	adocxt gen-include < $< > $@
+
+clean:
+	$(RM) -r generated-sources

doc/toolchain/bin/adocxt

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+
+
+import re
+import shlex
+import sys
+import typing
+
+
+RE_FROM_CODE = re.compile(r'^\[\[([^,]+),[^,]*,From Code]]$')
+RE_TAG = re.compile('^cmdhelp_(.*)$')
+
+TAG_EXCLUDES = {
+    'cmdhelp_node_online',
+    'cmdhelp_node_standby',
+    'cmdhelp_root_report',
+}
+
+
+def main(stdin, stdout):
+    tags = list()
+    for line in stdin:
+        found = RE_FROM_CODE.match(line)
+        if found:
+            tag = found.group(1)
+            if tag in TAG_EXCLUDES:
+                continue
+            command = extract_command(tag)
+            tags.append(tag)
+            stdout.write(tag)
+            stdout.write('.txt:\n\t')
+            stdout.write(shlex.join(command))
+            stdout.write(' > "$@"\n\n')
+    end(tags, stdout)
+
+
+def extract_command(tag: str) -> typing.Sequence[str]:
+    found = RE_TAG.match(tag)
+    if not found:
+        raise RuntimeError(f'Invalid tag {tag}')
+    args = ['crm']
+    args.extend(found.group(1).split('_', 1))
+    args.append('--help-without-redirect')
+    return args
+
+
+def end(tags: typing.Sequence[str], stdout):
+    stdout.write(
+        '%.adoc: %.txt\n\thelp2adoc "$<"\n\n'
+    )
+    stdout.write(
+        '.PHONY: clean all\n\nclean:\n\t$RM *.txt *.adoc\n\nall: '
+    )
+    for tag in tags:
+        stdout.write(tag)
+        stdout.write('.adoc ')
+    stdout.write('\n\n')
+
+
+
+if __name__ == '__main__':
+    main(sys.stdin, sys.stdout)