[Bf-blender-cvs] [52b93c423dc] master: TEST COMMIT: API doc generation changes.
Bastien Montagne
noreply at git.blender.org
Fri Jun 17 16:40:18 CEST 2022
Commit: 52b93c423dc0db774dbcfb656702ecc01f8d6818
Author: Bastien Montagne
Date: Fri Jun 17 16:39:36 2022 +0200
Branches: master
https://developer.blender.org/rB52b93c423dc0db774dbcfb656702ecc01f8d6818
TEST COMMIT: API doc generation changes.
This commit is intended to be reverted within a few minutes.
commit 9442d8ef0f255d3c18b610b42aff71229904aaee
Author: Bastien Montagne <bastien at blender.org>
Date: Wed Jun 15 15:43:13 2022 +0200
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.
commit f7fb537078641d2e2de015c08554f5281ce9debd
Author: Bastien Montagne <bastien at blender.org>
Date: Wed Jun 15 15:36:19 2022 +0200
Py API Doc: refactor changelog generation script.
Main change is to make it use JSON format for its dump files, instead of
some Python code.
It also introduces an index for those API dump files, mapping a blender
version to the relevant file path.
This is then used to automatically the most recent (version-number wise)
previous API dump to compare against current one, when generating the
change log RST file.
===================================================================
M doc/python_api/sphinx_changelog_gen.py
M doc/python_api/sphinx_doc_gen.py
===================================================================
diff --git a/doc/python_api/sphinx_changelog_gen.py b/doc/python_api/sphinx_changelog_gen.py
index a782c6483b6..6063081b3ba 100644
--- a/doc/python_api/sphinx_changelog_gen.py
+++ b/doc/python_api/sphinx_changelog_gen.py
@@ -1,59 +1,112 @@
# SPDX-License-Identifier: GPL-2.0-or-later
"""
-Dump the python API into a text file so we can generate changelogs.
+---------------
-output from this tool should be added into "doc/python_api/rst/change_log.rst"
+Dump the python API into a JSON file, or generate changelogs from those JSON API dumps.
-# dump api blender_version.py in CWD
-blender --background --python doc/python_api/sphinx_changelog_gen.py -- --dump
+Typically, changelog output from this tool should be added into "doc/python_api/rst/change_log.rst"
-# create changelog
-blender --background --factory-startup --python doc/python_api/sphinx_changelog_gen.py -- \
- --api_from blender_2_63_0.py \
- --api_to blender_2_64_0.py \
- --api_out changes.rst
+API dump files are saved together with the generated API doc on the server, with a general index file.
+This way the changelog generation simply needs to re-download the previous version's dump for the diffing process.
+
+---------------
+# Dump api blender_version.json in CWD:
+blender --background --factory-startup --python doc/python_api/sphinx_changelog_gen.py -- \
+ --indexpath="path/to/api/docs/api_dump_index.json" \
+ dump --filepath-out="path/to/api/docs/<version>/api_dump.json"
+
+# Create changelog:
+blender --background --factory-startup --python doc/python_api/sphinx_changelog_gen.py -- \
+ --indexpath="path/to/api/docs/api_dump_index.json" \
+ changelog --filepath-out doc/python_api/rst/change_log.rst
-# Api comparison can also run without blender
+# Api comparison can also run without blender,
+# will by default generate changeloig between the last two available versions listed in the index,
+# unless input files are provided explicitely:
python doc/python_api/sphinx_changelog_gen.py -- \
- --api_from blender_api_2_63_0.py \
- --api_to blender_api_2_64_0.py \
- --api_out changes.rst
+ --indexpath="path/to/api/docs/api_dump_index.json" \
+ changelog --filepath-in-from blender_api_2_63_0.json \
+ --filepath-in-to blender_api_2_64_0.json \
+ --filepath-out changes.rst
-# Save the latest API dump in this folder, renaming it with its revision.
-# This way the next person updating it doesn't need to build an old Blender only for that
+--------------
-"""
+API dump index format:
-# format
-'''
-{"module.name":
- {"parent.class":
- {"basic_type", "member_name":
- ("Name", type, range, length, default, descr, f_args, f_arg_types, f_ret_types)}, ...
- }, ...
+{[version_main, version_sub]: "<version>/api_dump.json", ...
}
-'''
-api_names = "basic_type" "name", "type", "range", "length", "default", "descr", "f_args", "f_arg_types", "f_ret_types"
+API dump format:
+
+[
+ [version_main, vserion_sub, version_path],
+ {"module.name":
+ {"parent.class":
+ {"basic_type", "member_name":
+ ["Name", type, range, length, default, descr, f_args, f_arg_types, f_ret_types]}, ...
+ }, ...
+ }
+]
+"""
+
+import json
+import os
+
+
+api_names = "basic_type" "name", "type", "range", "length", "default", "descr", "f_args", "f_arg_types", "f_ret_types"
API_BASIC_TYPE = 0
API_F_ARGS = 7
-def api_dunp_fname():
- import bpy
- return "blender_api_%s.py" % "_".join([str(i) for i in bpy.app.version])
+def api_version():
+ try:
+ import bpy
+ except:
+ return None, None
+ version = tuple(bpy.app.version[:2])
+ version_key = "%d.%d" % (version[0], version[1])
+ return version, version_key
+
+
+def api_version_previous_in_index(index, version):
+ print("Searching for previous version to %s in %r" % (version, index))
+ version_prev = (version[0], version[1])
+ while True:
+ version_prev = (version_prev[0], version_prev[1] - 1)
+ if version_prev[1] < 0:
+ version_prev = (version_prev[0] - 1, 99)
+ if version_prev[0] < 0:
+ return None, None
+ version_prev_key = "%d.%d" % (version_prev[0], version_prev[1])
+ print("Checking for previous version %s" % (version_prev,))
+ if version_prev_key in index:
+ print("Found previous version %s: %r" % (version_prev, index[version_prev_key]))
+ return version_prev, version_prev_key
+
+
+class JSONEncoderAPIDump(json.JSONEncoder):
+ def default(self, o):
+ if o is ...:
+ return "..."
+ if isinstance(o, set):
+ return tuple(o)
+ return json.JSONEncoder.default(self, o)
+
+
+def api_dump(args):
+ import rna_info
+ import inspect
+ version, version_key = api_version()
+ if version is None:
+ raise(ValueError("API dumps can only be generated from within Blender."))
-def api_dump():
dump = {}
dump_module = dump["bpy.types"] = {}
- import rna_info
- import inspect
-
struct = rna_info.BuildRNAInfo()[0]
for struct_id, struct_info in sorted(struct.items()):
@@ -155,17 +208,26 @@ def api_dump():
)
del funcs
- import pprint
+ filepath_out = args.filepath_out
+ with open(filepath_out, 'w', encoding='utf-8') as file_handle:
+ json.dump((version, dump), file_handle, cls=JSONEncoderAPIDump)
- filename = api_dunp_fname()
- filehandle = open(filename, 'w', encoding='utf-8')
- tot = filehandle.write(pprint.pformat(dump, width=1))
- filehandle.close()
- print("%s, %d bytes written" % (filename, tot))
+ indexpath = args.indexpath
+ rootpath = os.path.dirname(indexpath)
+ if os.path.exists(indexpath):
+ with open(indexpath, 'r', encoding='utf-8') as file_handle:
+ index = json.load(file_handle)
+ else:
+ index = {}
+ index[version_key] = os.path.relpath(filepath_out, rootpath)
+ with open(indexpath, 'w', encoding='utf-8') as file_handle:
+ json.dump(index, file_handle)
+ print("API version %s dumped into %r, and index %r has been updated" % (version_key, filepath_out, indexpath))
+ print(index)
-def compare_props(a, b, fuzz=0.75):
+def compare_props(a, b, fuzz=0.75):
# must be same basic_type, function != property
if a[0] != b[0]:
return False
@@ -180,15 +242,45 @@ def compare_props(a, b, fuzz=0.75):
return ((tot / totlen) >= fuzz)
-def api_changelog(api_from, api_to, api_out):
+def api_changelog(args):
+ indexpath = args.indexpath
+ filepath_in_from = args.filepath_in_from
+ filepath_in_to = args.filepath_in_to
+ filepath_out = args.filepath_out
+
+ rootpath = os.path.dirname(indexpath)
+
+ version, version_key = api_version()
+ if version is None and (filepath_in_from is None or filepath_in_to is None):
+ raise(ValueError("API dumps files must be given when ran outside of Blender."))
+
+ with open(indexpath, 'r', encoding='utf-8') as file_handle:
+ index = json.load(file_handle)
+
+ if filepath_in_to == None:
+ filepath_in_to = index.get(version_key, None)
+ if filepath_in_to == None:
+ raise(ValueError("Cannot find API dump file for Blender version " + str(version) + " in index file."))
+
+ print("Found to file: %r" % filepath_in_to)
- file_handle = open(api_from, 'r', encoding='utf-8')
- dict_from = eval(file_handle.read())
- file_handle.close()
+ if filepath_in_from == None:
+ version_from, version_from_key = api_version_previous_in_index(index, version)
+ if version_from is None:
+ raise(ValueError("No previous version of Blender could be found in the index."))
+ filepath_in_from = index.get(version_from_key, None)
+ if filepath_in_from is None:
+ raise(ValueError("Cannot find API dump file for previous Blender version " + str(version_from) + " in index file."))
- file_handle = open(api_to, 'r', encoding='utf-8')
- dict_to = eval(file_handle.read())
- file_handle.close()
+ print("Found from file: %r" % filepath_in_from)
+
+
+ with open(os.path.join(rootpath, filepath_in_from), 'r', encoding='utf-8') as file_handle:
+ _, dict_from = json.load(file_handle)
+
+ with open(os.path.join(rootpath, filepath_in_to), 'r', encoding='utf-8') as file_handle:
+ dump_version, dict_to = json.load(file_handle)
+ assert(tuple(dump_version) == version)
api_changes = []
@@ -249,63 +341,69 @@ def api_changelog(api_from, api_to, api_out):
# also document function argument changes
- fout = open(api_out, 'w', encoding='utf-8')
- fw = fout.write
- # print(api_changes)
-
- # :class:`bpy_struct.id_data`
-
- def write_title(title, title_char):
- fw("%s\n%s\n\n" % (title, title_char * len(title)))
-
- for mod_id, class_id, props_moved, props_new, props_old, func_args in api_changes:
- class_name = class_id.split(".")[-1]
- title = mod_id + "." + class_name
- write_title(title, "-")
-
- if props_new:
- write_title("Added", "^")
- for prop_id in props_new:
- fw("* :class:`%s.%s.%s`\n" % (mod_id, class_name, prop_id))
- fw("\n")
-
- if props_old:
- write_title("Removed", "^")
- for prop_id in props_old:
- fw("* **%s**\n" % prop_id) # can't link to removed docs
- fw("\n")
-
- if props_moved:
- write_title("Renamed", "^")
- for prop_id_old, prop_id in props_moved:
- fw("* **%s** -> :class:`%s.%s.%s`\n" % (prop_id_old, mod_id, class_name, prop_id))
- fw("\n")
-
- if func_args:
- write_title("Function Arguments", "^")
- for func_id, args_old, args_new in func_args:
- args_new = ", ".join(args_new)
- args_old = ", ".join(args_old)
- fw("* :class:`%s.%s.%s` (%s), *was (%s)*\n" % (mod_id, class_name, func_id, args_new, args_old))
- fw("\n")
-
- fout.close()
-
- print("Written: %r"
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list