- include enum names and descriptions in sphinx generated documentation

- add descriptions for operator bl_options

1 files changed, 53 insertions, 4 deletions

diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index ac2a498efc2..dec4a7a4c99 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -76,7 +76,7 @@ else:
         "bpy.props",
         "bpy.utils",
         "bpy.context",
-        "bpy.types",  # supports filtering
+        # "bpy.types",  # supports filtering
         "bpy.ops",  # supports filtering
         "bpy_extras",
         "bge",
@@ -87,7 +87,7 @@ else:
         "mathutils.geometry",
     )
 
-    FILTER_BPY_TYPES = ("bpy_struct", "Panel", "ID")  # allow
+    FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID")  # allow
     FILTER_BPY_OPS = ("import.scene", )  # allow
 
     # for quick rebuilds
@@ -621,6 +621,30 @@ def pycontext2sphinx(BASEPATH):
     file.close()
 
 
+def pyrna_enum2sphinx(prop, use_empty_descriptions=True):
+    """ write a bullet point list of enum + descrptons
+    """
+
+    if use_empty_descriptions:
+        ok = True
+    else:
+        ok = False
+        for identifier, name, description in prop.enum_items:
+            if description:
+                ok = True
+                break
+
+    if ok:
+        return "".join(["* ``%s`` %s.\n" %
+                        (identifier,
+                         ", ".join(val for val in (name, description) if val),
+                         )
+                        for identifier, name, description in prop.enum_items
+                        ])
+    else:
+        return ""
+
+
 def pyrna2sphinx(BASEPATH):
     """ bpy.types and bpy.ops
     """
@@ -648,8 +672,22 @@ def pyrna2sphinx(BASEPATH):
         kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID
 
         type_descr = prop.get_type_description(**kwargs)
-        if prop.name or prop.description:
-            fw(ident + ":%s%s: %s\n" % (id_name, identifier, ", ".join(val for val in (prop.name, prop.description) if val)))
+
+        enum_text = pyrna_enum2sphinx(prop)
+
+        if prop.name or prop.description or enum_text:
+            fw(ident + ":%s%s:\n\n" % (id_name, identifier))
+
+            if prop.name or prop.description:
+                fw(ident + "   " + ", ".join(val for val in (prop.name, prop.description) if val) + "\n\n")
+
+            # special exception, cant use genric code here for enums
+            if enum_text:
+                write_indented_lines(ident + "   ", fw, enum_text)
+                fw("\n")
+            del enum_text
+            # end enum exception
+
         fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr))
 
     def write_struct(struct):
@@ -727,6 +765,16 @@ def pyrna2sphinx(BASEPATH):
                 fw("   .. attribute:: %s\n\n" % prop.identifier)
             if prop.description:
                 fw("      %s\n\n" % prop.description)
+            
+            # special exception, cant use genric code here for enums
+            if prop.type == "enum":
+                enum_text = pyrna_enum2sphinx(prop)
+                if enum_text:
+                    write_indented_lines("      ", fw, enum_text)
+                    fw("\n")
+                del enum_text
+            # end enum exception
+
             fw("      :type: %s\n\n" % type_descr)
 
         # python attributes
@@ -750,6 +798,7 @@ def pyrna2sphinx(BASEPATH):
             elif func.return_values:  # multiple return values
                 fw("      :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
                 for prop in func.return_values:
+                    # TODO, pyrna_enum2sphinx for multiple return values... actually dont think we even use this but still!!!
                     type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID)
                     descr = prop.description
                     if not descr: