- include enum names and descriptions in sphinx generated documentation

- add descriptions for operator bl_options

6 files changed, 100 insertions, 38 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
diff --git a/release/scripts/modules/rna_info.py b/release/scripts/modules/rna_info.py
index 943f86adecb..d95c3920cf9 100644
--- a/release/scripts/modules/rna_info.py
+++ b/release/scripts/modules/rna_info.py
@@ -207,7 +207,7 @@ class InfoPropertyRNA:
             self.fixed_type = None
 
         if self.type == "enum":
-            self.enum_items[:] = rna_prop.enum_items.keys()
+            self.enum_items[:] = [(item.identifier, item.name, item.description) for item in rna_prop.enum_items]
             self.is_enum_flag = rna_prop.is_enum_flag
         else:
             self.is_enum_flag = False
@@ -264,9 +264,9 @@ class InfoPropertyRNA:
                 type_str += " in [%s, %s]" % (range_str(self.min), range_str(self.max))
             elif self.type == "enum":
                 if self.is_enum_flag:
-                    type_str += " set in {%s}" % ", ".join(("'%s'" % s) for s in self.enum_items)
+                    type_str += " set in {%s}" % ", ".join(("'%s'" % s[0]) for s in self.enum_items)
                 else:
-                    type_str += " in [%s]" % ", ".join(("'%s'" % s) for s in self.enum_items)
+                    type_str += " in [%s]" % ", ".join(("'%s'" % s[0]) for s in self.enum_items)
 
             if not (as_arg or as_ret):
                 # write default property, ignore function args for this
diff --git a/source/blender/blenlib/intern/string_utf8.c b/source/blender/blenlib/intern/string_utf8.c
index 5c37d3003e4..d39bb498538 100644
--- a/source/blender/blenlib/intern/string_utf8.c
+++ b/source/blender/blenlib/intern/string_utf8.c
@@ -145,18 +145,18 @@ int BLI_utf8_invalid_strip(char *str, int length)
 
 /* compatible with BLI_strncpy, but esnure no partial utf8 chars */
 
-/* array copied from glib's glib's gutf8.c,
+/* array copied from glib's gutf8.c,
  * note: this looks to be at odd's with 'trailingBytesForUTF8',
  * need to find out what gives here! - campbell */
 static const size_t utf8_skip_data[256] = {
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
-  2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
-  3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,4,4,4,4,4,4,4,4,5,5,5,5,6,6,1,1
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,3,4,4,4,4,4,4,4,4,5,5,5,5,6,6,1,1
 };
 
 char *BLI_strncpy_utf8(char *dst, const char *src, size_t maxncpy)
diff --git a/source/blender/makesrna/intern/rna_wm.c b/source/blender/makesrna/intern/rna_wm.c
index 7ce1e1ab88f..a259f84ff1a 100644
--- a/source/blender/makesrna/intern/rna_wm.c
+++ b/source/blender/makesrna/intern/rna_wm.c
@@ -348,20 +348,20 @@ EnumPropertyItem keymap_modifiers_items[] = {
 		{0, NULL, 0, NULL, NULL}};
 
 EnumPropertyItem operator_flag_items[] = {
-		{OPTYPE_REGISTER, "REGISTER", 0, "Register", ""},
-		{OPTYPE_UNDO, "UNDO", 0, "Undo", ""},
-		{OPTYPE_BLOCKING, "BLOCKING", 0, "Blocking", ""},
-		{OPTYPE_MACRO, "MACRO", 0, "Macro", ""},
-		{OPTYPE_GRAB_POINTER, "GRAB_POINTER", 0, "Grab Pointer", ""},
-		{OPTYPE_PRESET, "PRESET", 0, "Preset", ""},
-		{OPTYPE_INTERNAL, "INTERNAL", 0, "Internal", ""},
+		{OPTYPE_REGISTER, "REGISTER", 0, "Register", "Display in the info window and support the redo toolbar panel"},
+		{OPTYPE_UNDO, "UNDO", 0, "Undo", "Push an undo event (needed for operator redo)"},
+		{OPTYPE_BLOCKING, "BLOCKING", 0, "Blocking", "Block anything else from using the cursor"},
+		{OPTYPE_MACRO, "MACRO", 0, "Macro", "Use to check if an operator is a macro"},
+		{OPTYPE_GRAB_POINTER, "GRAB_POINTER", 0, "Grab Pointer", "Use so the operator grabs the mouse focus, enables wrapping when continuous grab is enabled"},
+		{OPTYPE_PRESET, "PRESET", 0, "Preset", "Display a preset button with the operators settings"},
+		{OPTYPE_INTERNAL, "INTERNAL", 0, "Internal", "Removes the operator from search results"},
 		{0, NULL, 0, NULL, NULL}};
 
 EnumPropertyItem operator_return_items[] = {
-		{OPERATOR_RUNNING_MODAL, "RUNNING_MODAL", 0, "Running Modal", ""},
-		{OPERATOR_CANCELLED, "CANCELLED", 0, "Cancelled", ""},
-		{OPERATOR_FINISHED, "FINISHED", 0, "Finished", ""},
-		{OPERATOR_PASS_THROUGH, "PASS_THROUGH", 0, "Pass Through", ""}, // used as a flag
+		{OPERATOR_RUNNING_MODAL, "RUNNING_MODAL", 0, "Running Modal", "Keep the operator running with blender"},
+		{OPERATOR_CANCELLED, "CANCELLED", 0, "Cancelled", "When no action has been taken, operator exits"},
+		{OPERATOR_FINISHED, "FINISHED", 0, "Finished", "When the operator is complete, operator exits"},
+		{OPERATOR_PASS_THROUGH, "PASS_THROUGH", 0, "Pass Through", "Do nothing and pass the event on"}, // used as a flag
 		{0, NULL, 0, NULL, NULL}};
 
 /* flag/enum */