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.

1 files changed, 85 insertions, 0 deletions

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 <bpy_types_enum_items/index>\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)