- include enum names and descriptions in sphinx generated documentation

- add descriptions for operator bl_options

3 files changed, 77 insertions, 15 deletions

diff --git a/doc/python_api/examples/bpy.types.ID.user_clear.1.py b/doc/python_api/examples/bpy.types.ID.user_clear.1.py
index 68c35caa7d4..239ed41c66c 100644
--- a/doc/python_api/examples/bpy.types.ID.user_clear.1.py
+++ b/doc/python_api/examples/bpy.types.ID.user_clear.1.py
@@ -1,6 +1,4 @@
 """
-User Clear
-++++++++++
 This function is for advanced use only, misuse can crash blender since the user
 count is used to prevent data being removed when it is used.
 """
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:
diff --git a/doc/python_api/sphinx_doc_gen.sh b/doc/python_api/sphinx_doc_gen.sh
index ea55fbb3907..307476d9a92 100755
--- a/doc/python_api/sphinx_doc_gen.sh
+++ b/doc/python_api/sphinx_doc_gen.sh
@@ -9,6 +9,10 @@
 
 # disable for testing
 DO_UPLOAD=true
+DO_EXE_BLENDER=true
+DO_OUT_HTML=true
+DO_OUT_PDF=true
+
 
 BLENDER="./blender.bin"
 SSH_USER="ideasman42"
@@ -36,28 +40,39 @@ fi
 
 SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION
 
-SPHINXBASE=doc/python_api/
+SPHINXBASE=doc/python_api
 
 
 # ----------------------------------------------------------------------------
 # Generate reStructuredText (blender/python only)
 
-# dont delete existing docs, now partial updates are used for quick builds.
-$BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py
+if $DO_EXE_BLENDER ; then
+	# dont delete existing docs, now partial updates are used for quick builds.
+	$BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py
+fi
 
 
 # ----------------------------------------------------------------------------
 # Generate HTML (sphinx)
 
-sphinx-build -n -b html $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
+if $DO_OUT_HTML ; then
+	# sphinx-build -n -b html $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
+
+	# annoying bug in sphinx makes it very slow unless we do this. should report.
+	cd $SPHINXBASE
+	sphinx-build -n -b html sphinx-in sphinx-out
+	cd -
+fi
 
 
 # ----------------------------------------------------------------------------
 # Generate PDF (sphinx/laytex)
 
-sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
-make -C $SPHINXBASE/sphinx-out
-mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
+if $DO_OUT_PDF ; then
+	sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
+	make -C $SPHINXBASE/sphinx-out
+	mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
+fi
 
 # ----------------------------------------------------------------------------
 # Upload to blender servers, comment this section for testing
@@ -85,5 +100,5 @@ fi
 
 echo ""
 echo "Finished! view the docs from: "
-echo "  html:" $SPHINXBASE/sphinx-out/contents.html
-echo "   pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
+if $DO_OUT_HTML ; then echo "  html:" $SPHINXBASE/sphinx-out/contents.html ; fi
+if $DO_OUT_PDF ; then  echo "   pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi