From 9bb9a54a2aec6787a833f08da66d9a117c059ce1 Mon Sep 17 00:00:00 2001
From: Bastien Montagne <bastien@blender.org>
Date: Wed, 15 Jun 2022 15:43:13 +0200
Subject: Py API Doc: add runtime changelog generation to `sphinx_doc_gen.py`.

Optionally use `sphinx_changelog_gen.py` to dump current version of the
API in a JSON file, and use closest previous one listed in given index
file to create a changelog RST page for Sphinx.

Part of {T97663}.
---
 doc/python_api/sphinx_doc_gen.py | 43 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index d87d8b71ce5..684761f49c5 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -121,6 +121,26 @@ def handle_args():
                              "(default=False)",
                         required=False)
 
+    parser.add_argument(
+        "--api-changelog-generate",
+        dest="changelog",
+        default=False,
+        action='store_true',
+        help="Generate the API changelog RST file "
+        "(default=False, requires `--api-dump-index-path` parameter)",
+        required=False,
+    )
+
+    parser.add_argument(
+        "--api-dump-index-path",
+        dest="api_dump_index_path",
+        metavar='FILE',
+        default=None,
+        help="Path to the API dump index JSON file "
+        "(required when `--api-changelog-generate` is True)",
+        required=False,
+    )
+
     parser.add_argument("-o", "--output",
                         dest="output_dir",
                         type=str,
@@ -468,6 +488,26 @@ if ARGS.sphinx_build_pdf:
         sphinx_make_pdf_log = os.path.join(ARGS.output_dir, ".latex_make.log")
         SPHINX_MAKE_PDF_STDOUT = open(sphinx_make_pdf_log, "w", encoding="utf-8")
 
+
+# --------------------------------CHANGELOG GENERATION--------------------------------------
+
+def generate_changelog():
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("sphinx_changelog_gen",
+                                                  os.path.abspath(os.path.join(SCRIPT_DIR, "sphinx_changelog_gen.py")))
+    sphinx_changelog_gen = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(sphinx_changelog_gen)
+
+    API_DUMP_INDEX_FILEPATH = ARGS.api_dump_index_path
+    API_DUMP_ROOT = os.path.dirname(API_DUMP_INDEX_FILEPATH)
+    API_DUMP_FILEPATH = os.path.abspath(os.path.join(API_DUMP_ROOT, BLENDER_VERSION_DOTS, "api_dump.json"))
+    API_CHANGELOG_FILEPATH = os.path.abspath(os.path.join(SPHINX_IN_TMP, "change_log.rst"))
+
+    sphinx_changelog_gen.main(("--", "--indexpath", API_DUMP_INDEX_FILEPATH, "dump", "--filepath-out", API_DUMP_FILEPATH))
+
+    sphinx_changelog_gen.main(("--", "--indexpath", API_DUMP_INDEX_FILEPATH, "changelog", "--filepath-out", API_CHANGELOG_FILEPATH))
+
+
 # --------------------------------API DUMP--------------------------------------
 
 # lame, python won't give some access
@@ -2325,6 +2365,9 @@ def main():
 
     rna2sphinx(SPHINX_IN_TMP)
 
+    if ARGS.changelog:
+        generate_changelog()
+
     if ARGS.full_rebuild:
         # only for full updates
         shutil.rmtree(SPHINX_IN, True)
-- 
cgit v1.2.3