Dev: doc/toolchain: implement generating include statement for asciid…

…oc (ClusterLabs#1374)

To generate a complete document, those sections generated from argparse
help needed to be included from crm.8.adoc

doc/toolchain/bin/adocxt

@@ -9,6 +9,8 @@ import typing
 
 RE_FROM_CODE = re.compile(r'^\[\[([^,]+),[^,]*,From Code]]$')
 RE_TAG = re.compile('^cmdhelp_(.*)$')
+RE_SECTION_TITLE = re.compile('^=')
+RE_FROM_CODE_OR_SECTION_TITLE=re.compile(r'^(?:\[\[([^,]+),[^,]*,From Code]]$|=)')
 
 TAG_EXCLUDES = {
     'cmdhelp_node_online',
@@ -17,7 +19,7 @@ TAG_EXCLUDES = {
 }
 
 
-def main(stdin, stdout):
+def generate_makefile(stdin, stdout):
     tags = list()
     for line in stdin:
         found = RE_FROM_CODE.match(line)
@@ -46,7 +48,7 @@ def extract_command(tag: str) -> typing.Sequence[str]:
 
 def end(tags: typing.Sequence[str], stdout):
     stdout.write(
-        '%.adoc: %.txt\n\thelp2adoc "$<"\n\n'
+        '%.adoc: %.txt\n\thelp2adoc "$<" > "$*".adoc\n\n'
     )
     stdout.write(
         '.PHONY: clean all\n\nclean:\n\t$RM *.txt *.adoc\n\nall: '
@@ -57,6 +59,54 @@ def end(tags: typing.Sequence[str], stdout):
     stdout.write('\n\n')
 
 
+def generate_include(stdin, stdout):
+    tag = None
+    section_title = None
+    for line in stdin:
+        go_next_line = False
+        while not go_next_line:
+            match tag:
+                case None:
+                    # initial state
+                    found = RE_FROM_CODE.match(line)
+                    if found:
+                        found_tag = found.group(1)
+                        if found_tag not in TAG_EXCLUDES:
+                            tag = found_tag
+                    stdout.write(line)
+                    go_next_line = True
+                case _:
+                    # found a tag
+                    match section_title:
+                        case None:
+                            # waiting a section title
+                            found = RE_SECTION_TITLE.match(line)
+                            if found:
+                                section_title = line
+                                stdout.write(section_title)
+                                print(f'include::{tag}.adoc[]\n', file=stdout)
+                            break
+                        case _:
+                            # waiting for next section
+                            found = RE_FROM_CODE_OR_SECTION_TITLE.match(line)
+                            if found:
+                                tag = None
+                                section_title = None
+                            else:
+                                go_next_line = True
+
+
+def main():
+    if len(sys.argv) != 2:
+        print(f'Usage: {sys.argv[0]} gen-makefile|gen-include', file=sys.stderr)
+        return 1
+    match sys.argv[1]:
+        case 'gen-makefile':
+            generate_makefile(sys.stdin, sys.stdout)
+        case 'gen-include':
+            generate_include(sys.stdin, sys.stdout)
+
+
 
 if __name__ == '__main__':
-    main(sys.stdin, sys.stdout)
+    sys.exit(main())