tools_maintenance/blender_help_extract.py

@@ -1,24 +1,32 @@
 #!/usr/bin/env python3
 # Apache License, Version 2.0
 
+"""
+This script extracts RST fro Blender's "--help",
+using simple conventions & REGEX parsing.
+
+Example:
+   python tools_maintenance/blender_help_extract.py /path/to/blender manual/advanced/command_line/arguments.rst
+"""
+
+# Conversion from There are some cases which aren't handled (and aren't needed at the moment),
+# noting for completeness.
+#
+# - Multi-line code-blocks as each block is currently only a single line.
+# - Skip parsing text inside comment blocks (literal quoting single brackets for e.g.).
+
 import os
 import re
 import subprocess
 
 
-# This script extracts the '--help' message from Blender's source code,
-# using primitive regex parsing.
-#
-# e.g:
-# python tools_maintenance/blender_help_extract.py \
-#        /path/to/blender \
-#        manual/advanced/command_line/arguments.rst
-
 def help_text_make_version_and_usage_substitution(text: str) -> str:
-    re_version = re.compile(r"^(Blender )\d.*\n(Usage:\s+)(.*)$", flags=re.MULTILINE)
     text = re.sub(
-        re_version,
-        lambda x: "| " + x.group(1) + "|BLENDER_VERSION|\n| " + x.group(2) + "``" + x.group(3) + "``",
+        re.compile(r"^(Blender) +\d.*\n(Usage:) +(.*)$", flags=re.MULTILINE),
+        lambda x: (
+            "| {:s} |BLENDER_VERSION|\n"
+            "| {:s} ``{:s}``"
+        ).format(x.group(1), x.group(2), x.group(3)),
         text,
     )
     return text
@@ -26,17 +34,22 @@ def help_text_make_version_and_usage_substitution(text: str) -> str:
 
 def help_text_make_args_literal(text: str) -> str:
 
-    re_argument_command = re.compile(r"(\-+[A-Za-z\-]+)")
-
-    def re_argument_command_fn(x: re.Match[str]) -> str:
-        return "``" + x.group(1) + "``"
+    re_content_table = (
+        (
+            re.compile(r"(\-+[A-Za-z\-]+)"),
+            lambda x: "``" + x.group(1) + "``",
+        ),
+    )
 
     re_argument_line = re.compile(r"^(\s*)(\-+[A-Za-z\-]+.*)$", flags=re.MULTILINE)
 
     def re_argument_line_fn(x: re.Match[str]) -> str:
         indent = x.group(1)
         content = x.group(2)
-        content = re.sub(re_argument_command, re_argument_command_fn, content)
+
+        for re_expr, re_fn in re_content_table:
+            content = re.sub(re_expr, re_fn, content)
+
         # Weak but works to replace or's with commas.
         content = content.replace("`` or ``-", "``, ``-", 1)
         return indent + content
@@ -79,7 +92,7 @@ def help_text_make_title_and_dedent(text: str) -> str:
         ).format(
             "".join([(c if c.isalpha() else "-") for c in heading.lower()]),
             heading,
-            ("=" * len(heading)),
+            (title_char * len(heading)),
         )
 
     text = re.sub(re_title, re_title_fn, text)
@@ -168,9 +181,23 @@ def help_text_make_code_blocks(text: str) -> str:
 
 
 def help_text_as_rst(text: str) -> str:
+    text_header = (
+        ".. DO NOT EDIT THIS FILE, GENERATED BY '{:s}'\n"
+        "\n"
+        "   CHANGES TO THIS FILE MUST BE MADE IN BLENDER'S SOURCE CODE, SEE:\n"
+        "   https://projects.blender.org/blender/blender/src/branch/main/source/creator/creator_args.c\n"
+        "\n"
+        ".. _command_line-args:\n"
+        "\n"
+        "**********************\n"
+        "Command Line Arguments\n"
+        "**********************\n"
+        "\n"
+    ).format(os.path.basename(__file__))
+
     # Expand tabs & strip trailing space.
     text = text.expandtabs(3)
-    text = "\n".join([l.rstrip() for l in text.splitlines()]) + "\n"
+    text = "\n".join([line.rstrip() for line in text.splitlines()]) + "\n"
 
     text = help_text_make_version_and_usage_substitution(text)
     text = help_text_make_args_literal(text)
@@ -181,7 +208,9 @@ def help_text_as_rst(text: str) -> str:
 
     # Hack: `/?` is a special case.
     text = text.replace("\n/?\n", "\n``/?``\n", 1)
-    return text
+
+    # Apply the header last (no need for it to be parsed).
+    return text_header + text
 
 
 def main() -> None:
@@ -206,6 +235,7 @@ def main() -> None:
             blender_bin,
             "--factory-startup",
             "--background",
+            "--python-exit-code", "1",
             "--python-expr",
             # Code begin/end text because of Blender's chatty reporting of version and that it quit.
             (
@@ -224,20 +254,6 @@ def main() -> None:
 
     text_rst = help_text_as_rst(text)
 
-    text_rst = (
-        ".. DO NOT EDIT THIS FILE, GENERATED BY '{:s}'\n"
-        "\n"
-        "   CHANGES TO THIS FILE MUST BE MADE IN BLENDER'S SOURCE CODE, SEE:\n"
-        "   https://projects.blender.org/blender/blender/src/branch/main/source/creator/creator_args.c\n"
-        "\n"
-        ".. _command_line-args:\n"
-        "\n"
-        "**********************\n"
-        "Command Line Arguments\n"
-        "**********************\n"
-        "\n"
-    ).format(os.path.basename(__file__)) + text_rst
-
     with open(output_file, "w", encoding="utf-8") as fh:
         fh.write(text_rst)