- include enum names and descriptions in sphinx generated documentation
authorCampbell Barton <ideasman42@gmail.com>
Thu, 15 Sep 2011 16:15:24 +0000 (16:15 +0000)
committerCampbell Barton <ideasman42@gmail.com>
Thu, 15 Sep 2011 16:15:24 +0000 (16:15 +0000)
- add descriptions for operator bl_options

doc/python_api/examples/bpy.types.ID.user_clear.1.py
doc/python_api/sphinx_doc_gen.py
doc/python_api/sphinx_doc_gen.sh
release/scripts/modules/rna_info.py
source/blender/blenlib/intern/string_utf8.c
source/blender/makesrna/intern/rna_wm.c

index 68c35ca..239ed41 100644 (file)
@@ -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.
 """
index ac2a498..dec4a7a 100644 (file)
@@ -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:
index ea55fbb..307476d 100755 (executable)
@@ -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
index 943f86a..d95c392 100644 (file)
@@ -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
index 5c37d30..d39bb49 100644 (file)
@@ -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)
index 7ce1e1a..a259f84 100644 (file)
@@ -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 */