From fb86f3ee187327eb659daf6d17d9233ec78508bc Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Tue, 31 May 2022 14:07:10 +1000 Subject: PyDoc: document static enums from RNA_enum_items.h Create a page for every enum in RNA_enum_items.h, which includes the enum values and the doc-string for each item. Each page creates a references which the API reference can be linked to via the same name as the enum, so :ref:`rna_enum_icon_items` links to the list of icons for e.g. This has two main advantages: - No need to manually duplicate enum values in the doc-strings of functions defined in Python's C/API (not RNA defined functions), `bpy.props` for example. - The generated Python API docs can reference these instead of including the enums in-line - resulting in unreasonably long lists in the case if icons and event types (for example). These changes will be made separately. --- doc/python_api/sphinx_doc_gen.py | 85 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 85 insertions(+) (limited to 'doc') diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index b29251b67cc..ebaea669679 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -78,6 +78,17 @@ SCRIPT_DIR = os.path.abspath(os.path.dirname(__file__)) # See: D6261 for reference. USE_ONLY_BUILTIN_RNA_TYPES = True +# Write a page for each static enum defined in: +# `source/blender/makesrna/RNA_enum_items.h` so the enums can be linked to instead of being expanded everywhere. +USE_SHARED_RNA_ENUM_ITEMS_STATIC = True + +if USE_SHARED_RNA_ENUM_ITEMS_STATIC: + from _bpy import rna_enum_items_static + rna_enum_dict = rna_enum_items_static() + for key in ("DummyRNA_DEFAULT_items", "DummyRNA_NULL_items"): + del rna_enum_dict[key] + del key, rna_enum_items_static + def handle_args(): """ @@ -1978,6 +1989,14 @@ def write_rst_types_index(basepath): fw(".. toctree::\n") fw(" :glob:\n\n") fw(" bpy.types.*\n\n") + + # This needs to be included somewhere, while it's hidden, list to avoid warnings. + if USE_SHARED_RNA_ENUM_ITEMS_STATIC: + fw(".. toctree::\n") + fw(" :hidden:\n") + fw(" :maxdepth: 1\n\n") + fw(" Shared Enum Types \n\n") + file.close() @@ -2048,6 +2067,68 @@ def write_rst_data(basepath): EXAMPLE_SET_USED.add("bpy.data") +def write_rst_enum_items(basepath, key, key_no_prefix, enum_items): + """ + Write a single page for a static enum in RST. + + This helps avoiding very large lists being in-lined in many places which is an issue + especially with icons in ``bpy.types.UILayout``. See T87008. + """ + filepath = os.path.join(basepath, "%s.rst" % key_no_prefix) + with open(filepath, "w", encoding="utf-8") as fh: + fw = fh.write + # fw(".. noindex::\n\n") + fw(".. _%s:\n\n" % key) + + fw(title_string(key_no_prefix.replace("_", " ").title(), "#")) + # fw(".. rubric:: %s\n\n" % key_no_prefix.replace("_", " ").title()) + + for item in enum_items: + identifier = item.identifier + name = item.name + description = item.description + if identifier: + fw(":%s: %s\n" % (item.identifier, (escape_rst(name) + ".") if name else "")) + if description: + fw("\n") + write_indented_lines(" ", fw, escape_rst(description) + ".") + else: + fw("\n") + else: + if name: + fw("\n\n**%s**\n\n" % name) + else: + fw("\n\n----\n\n") + + if description: + fw(escape_rst(description) + ".") + fw("\n\n") + + +def write_rst_enum_items_and_index(basepath): + """ + Write shared enum items. + """ + subdir = "bpy_types_enum_items" + basepath_bpy_types_rna_enum = os.path.join(basepath, subdir) + os.makedirs(basepath_bpy_types_rna_enum, exist_ok=True) + with open(os.path.join(basepath_bpy_types_rna_enum, "index.rst"), "w", encoding="utf-8") as fh: + fw = fh.write + fw(title_string("Shared Enum Items", "#")) + fw(".. toctree::\n") + fw("\n") + for key, enum_items in rna_enum_dict.items(): + if not key.startswith("rna_enum_"): + raise Exception("Found RNA enum identifier that doesn't use the 'rna_enum_' prefix, found %r!", key) + key_no_prefix = key.removeprefix("rna_enum_") + fw(" %s\n" % key_no_prefix) + + for key, enum_items in rna_enum_dict.items(): + key_no_prefix = key.removeprefix("rna_enum_") + write_rst_enum_items(basepath_bpy_types_rna_enum, key, key_no_prefix, enum_items) + fw("\n") + + def write_rst_importable_modules(basepath): """ Write the RST files of importable modules. @@ -2212,6 +2293,10 @@ def rna2sphinx(basepath): write_rst_data(basepath) # bpy.data write_rst_importable_modules(basepath) + # `bpy_types_enum_items/*` (referenced from `bpy.types`). + if USE_SHARED_RNA_ENUM_ITEMS_STATIC: + write_rst_enum_items_and_index(basepath) + # copy the other rsts copy_handwritten_rsts(basepath) -- cgit v1.2.3