kannonier8/blender
1
0
Fork 0
forked from bartvdbraak/blender
Code Pull Requests Activity

- include enum names and descriptions in sphinx generated documentation

Browse Source 
- add descriptions for operator bl_options
This commit is contained in:
Campbell Barton 2011-09-15 16:15:24 +00:00
parent 2f50579d9a
commit e2818f1b92
6 changed files with 100 additions and 38 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/python_api/examples/bpy.types.ID.user_clear.1.py
View 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.
"""

57
doc/python_api/sphinx_doc_gen.py
View 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:

33
doc/python_api/sphinx_doc_gen.sh
View File

@ -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

6
release/scripts/modules/rna_info.py
View 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

18
source/blender/blenlib/intern/string_utf8.c
View 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)

22
source/blender/makesrna/intern/rna_wm.c
View 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 */