diff --git a/doc/python_api/rst/info_quickstart.rst b/doc/python_api/rst/info_quickstart.rst index d422bd9b656..418fab736a1 100644 --- a/doc/python_api/rst/info_quickstart.rst +++ b/doc/python_api/rst/info_quickstart.rst @@ -161,6 +161,8 @@ Data is added and removed via methods on the collections in :mod:`bpy.data`, e.g >>> bpy.data.meshes.remove(mesh) +.. _info_quickstart-custom_properties: + Custom Properties ^^^^^^^^^^^^^^^^^ @@ -197,6 +199,9 @@ Note that these properties can only be assigned basic Python types: These properties are valid outside of Python. They can be animated by curves or used in driver paths. +For a list of types that support custom properties see: +:ref:`types supporting custom properties `. + Context ------- diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py index 3840061a9a9..5b41109d3d8 100644 --- a/doc/python_api/sphinx_doc_gen.py +++ b/doc/python_api/sphinx_doc_gen.py @@ -84,6 +84,10 @@ USE_ONLY_BUILTIN_RNA_TYPES = True # `source/blender/makesrna/RNA_enum_items.hh` so the enums can be linked to instead of being expanded everywhere. USE_SHARED_RNA_ENUM_ITEMS_STATIC = True +# Generate a list of types which support custom properties. +# This isn't listed anywhere, it's just linked to. +USE_RNA_TYPES_WITH_CUSTOM_PROPERTY_INDEX = True + # Other types are assumed to be `bpy.types.*`. PRIMITIVE_TYPE_NAMES = {"bool", "bytearray", "bytes", "dict", "float", "int", "list", "set", "str", "tuple"} @@ -2136,6 +2140,13 @@ def write_rst_types_index(basepath): fw(" :maxdepth: 1\n\n") fw(" Shared Enum Types \n\n") + # This needs to be included somewhere, while it's hidden, list to avoid warnings. + if USE_RNA_TYPES_WITH_CUSTOM_PROPERTY_INDEX: + fw(".. toctree::\n") + fw(" :hidden:\n") + fw(" :maxdepth: 1\n\n") + fw(" Types with Custom Property Support \n\n") + def write_rst_ops_index(basepath): """ @@ -2302,6 +2313,49 @@ def write_rst_enum_items_and_index(basepath): fw("\n") +def write_rst_rna_types_with_custom_property_support(basepath): + from bpy.types import bpy_struct_meta_idprop + + types_exclude = { + "IDPropertyWrapPtr", # Internal type, exclude form public docs. + } + types_found = [] + + for ty_id in dir(bpy.types): + if ty_id.startswith("_"): + continue + if ty_id in types_exclude: + continue + + ty = getattr(bpy.types, ty_id) + if not isinstance(ty, bpy_struct_meta_idprop): + continue + + # Don't include every sub-type as it's very noisy and not helpful. + if any((isinstance(ty_base, bpy_struct_meta_idprop) for ty_base in ty.__bases__)): + continue + + types_found.append(ty_id) + + types_found.sort() + + with open(os.path.join(basepath, "bpy_types_custom_properties.rst"), "w", encoding="utf-8") as fh: + fw = fh.write + + fw(".. _bpy_types-custom_properties:\n\n") + + fw(title_string("Types with Custom Property Support", "=")) + fw("\n") + fw("The following types (and their sub-types) have custom-property access.\n\n") + + fw("For examples on using custom properties see the quick-start section on\n") + fw(":ref:`info_quickstart-custom_properties`.\n") + + fw("\n") + for ty_id in types_found: + fw("- :class:`bpy.types.{:s}`\n".format(ty_id)) + + def write_rst_importable_modules(basepath): """ Write the RST files of importable modules. @@ -2493,6 +2547,9 @@ def rna2sphinx(basepath): if USE_SHARED_RNA_ENUM_ITEMS_STATIC: write_rst_enum_items_and_index(basepath) + if USE_RNA_TYPES_WITH_CUSTOM_PROPERTY_INDEX: + write_rst_rna_types_with_custom_property_support(basepath) + # Copy the other RST files. copy_handwritten_rsts(basepath) diff --git a/source/blender/python/intern/bpy_rna.cc b/source/blender/python/intern/bpy_rna.cc index f82d16fd50c..3fea05dce97 100644 --- a/source/blender/python/intern/bpy_rna.cc +++ b/source/blender/python/intern/bpy_rna.cc @@ -137,11 +137,14 @@ static PyObject *pyrna_unregister_class(PyObject *self, PyObject *py_class); static StructRNA *srna_from_ptr(PointerRNA *ptr); +/** + * The `bpy_types-custom_properties` references is created as part of API doc generation. + * When expanded line reads: "Limited to: Types with Custom Property Support". + */ #define BPY_DOC_ID_PROP_TYPE_NOTE \ " .. note::\n" \ "\n" \ - " Only the :class:`bpy.types.ID`, :class:`bpy.types.Bone` and\n" \ - " :class:`bpy.types.PoseBone` classes support custom properties.\n" + " Limited to: :ref:`bpy_types-custom_properties`.\n" int pyrna_struct_validity_check_only(const BPy_StructRNA *pysrna) {