From e2818f1b926b779b1d59010aaa5c4e625c0877d5 Mon Sep 17 00:00:00 2001 From: Campbell Barton Date: Thu, 15 Sep 2011 16:15:24 +0000 Subject: - include enum names and descriptions in sphinx generated documentation - add descriptions for operator bl_options --- .../examples/bpy.types.ID.user_clear.1.py | 2 - doc/python_api/sphinx_doc_gen.py | 57 ++++++++++++++++++++-- doc/python_api/sphinx_doc_gen.sh | 33 +++++++++---- release/scripts/modules/rna_info.py | 6 +-- source/blender/blenlib/intern/string_utf8.c | 18 +++---- source/blender/makesrna/intern/rna_wm.c | 22 ++++----- 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 */ -- cgit v1.2.3