forked from bartvdbraak/blender
- include enum names and descriptions in sphinx generated documentation
- add descriptions for operator bl_options
This commit is contained in:
parent
2f50579d9a
commit
e2818f1b92
@ -1,6 +1,4 @@
|
|||||||
"""
|
"""
|
||||||
User Clear
|
|
||||||
++++++++++
|
|
||||||
This function is for advanced use only, misuse can crash blender since the user
|
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.
|
count is used to prevent data being removed when it is used.
|
||||||
"""
|
"""
|
||||||
|
@ -76,7 +76,7 @@ else:
|
|||||||
"bpy.props",
|
"bpy.props",
|
||||||
"bpy.utils",
|
"bpy.utils",
|
||||||
"bpy.context",
|
"bpy.context",
|
||||||
"bpy.types", # supports filtering
|
# "bpy.types", # supports filtering
|
||||||
"bpy.ops", # supports filtering
|
"bpy.ops", # supports filtering
|
||||||
"bpy_extras",
|
"bpy_extras",
|
||||||
"bge",
|
"bge",
|
||||||
@ -87,7 +87,7 @@ else:
|
|||||||
"mathutils.geometry",
|
"mathutils.geometry",
|
||||||
)
|
)
|
||||||
|
|
||||||
FILTER_BPY_TYPES = ("bpy_struct", "Panel", "ID") # allow
|
FILTER_BPY_TYPES = ("bpy_struct", "Operator", "ID") # allow
|
||||||
FILTER_BPY_OPS = ("import.scene", ) # allow
|
FILTER_BPY_OPS = ("import.scene", ) # allow
|
||||||
|
|
||||||
# for quick rebuilds
|
# for quick rebuilds
|
||||||
@ -621,6 +621,30 @@ def pycontext2sphinx(BASEPATH):
|
|||||||
file.close()
|
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):
|
def pyrna2sphinx(BASEPATH):
|
||||||
""" bpy.types and bpy.ops
|
""" bpy.types and bpy.ops
|
||||||
"""
|
"""
|
||||||
@ -648,8 +672,22 @@ def pyrna2sphinx(BASEPATH):
|
|||||||
kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID
|
kwargs["collection_id"] = _BPY_PROP_COLLECTION_ID
|
||||||
|
|
||||||
type_descr = prop.get_type_description(**kwargs)
|
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))
|
fw(ident + ":%s%s: %s\n" % (id_type, identifier, type_descr))
|
||||||
|
|
||||||
def write_struct(struct):
|
def write_struct(struct):
|
||||||
@ -727,6 +765,16 @@ def pyrna2sphinx(BASEPATH):
|
|||||||
fw(" .. attribute:: %s\n\n" % prop.identifier)
|
fw(" .. attribute:: %s\n\n" % prop.identifier)
|
||||||
if prop.description:
|
if prop.description:
|
||||||
fw(" %s\n\n" % 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)
|
fw(" :type: %s\n\n" % type_descr)
|
||||||
|
|
||||||
# python attributes
|
# python attributes
|
||||||
@ -750,6 +798,7 @@ def pyrna2sphinx(BASEPATH):
|
|||||||
elif func.return_values: # multiple return values
|
elif func.return_values: # multiple return values
|
||||||
fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
|
fw(" :return (%s):\n" % ", ".join(prop.identifier for prop in func.return_values))
|
||||||
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)
|
type_descr = prop.get_type_description(as_ret=True, class_fmt=":class:`%s`", collection_id=_BPY_PROP_COLLECTION_ID)
|
||||||
descr = prop.description
|
descr = prop.description
|
||||||
if not descr:
|
if not descr:
|
||||||
|
@ -9,6 +9,10 @@
|
|||||||
|
|
||||||
# disable for testing
|
# disable for testing
|
||||||
DO_UPLOAD=true
|
DO_UPLOAD=true
|
||||||
|
DO_EXE_BLENDER=true
|
||||||
|
DO_OUT_HTML=true
|
||||||
|
DO_OUT_PDF=true
|
||||||
|
|
||||||
|
|
||||||
BLENDER="./blender.bin"
|
BLENDER="./blender.bin"
|
||||||
SSH_USER="ideasman42"
|
SSH_USER="ideasman42"
|
||||||
@ -36,28 +40,39 @@ fi
|
|||||||
|
|
||||||
SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION
|
SSH_UPLOAD_FULL=$SSH_UPLOAD/"blender_python_api_"$BLENDER_VERSION
|
||||||
|
|
||||||
SPHINXBASE=doc/python_api/
|
SPHINXBASE=doc/python_api
|
||||||
|
|
||||||
|
|
||||||
# ----------------------------------------------------------------------------
|
# ----------------------------------------------------------------------------
|
||||||
# Generate reStructuredText (blender/python only)
|
# Generate reStructuredText (blender/python only)
|
||||||
|
|
||||||
# dont delete existing docs, now partial updates are used for quick builds.
|
if $DO_EXE_BLENDER ; then
|
||||||
$BLENDER --background --factory-startup --python $SPHINXBASE/sphinx_doc_gen.py
|
# 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)
|
# 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)
|
# Generate PDF (sphinx/laytex)
|
||||||
|
|
||||||
sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
|
if $DO_OUT_PDF ; then
|
||||||
make -C $SPHINXBASE/sphinx-out
|
sphinx-build -n -b latex $SPHINXBASE/sphinx-in $SPHINXBASE/sphinx-out
|
||||||
mv $SPHINXBASE/sphinx-out/contents.pdf $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
|
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
|
# Upload to blender servers, comment this section for testing
|
||||||
@ -85,5 +100,5 @@ fi
|
|||||||
|
|
||||||
echo ""
|
echo ""
|
||||||
echo "Finished! view the docs from: "
|
echo "Finished! view the docs from: "
|
||||||
echo " html:" $SPHINXBASE/sphinx-out/contents.html
|
if $DO_OUT_HTML ; then echo " html:" $SPHINXBASE/sphinx-out/contents.html ; fi
|
||||||
echo " pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf
|
if $DO_OUT_PDF ; then echo " pdf:" $SPHINXBASE/sphinx-out/blender_python_reference_$BLENDER_VERSION.pdf ; fi
|
||||||
|
@ -207,7 +207,7 @@ class InfoPropertyRNA:
|
|||||||
self.fixed_type = None
|
self.fixed_type = None
|
||||||
|
|
||||||
if self.type == "enum":
|
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
|
self.is_enum_flag = rna_prop.is_enum_flag
|
||||||
else:
|
else:
|
||||||
self.is_enum_flag = False
|
self.is_enum_flag = False
|
||||||
@ -264,9 +264,9 @@ class InfoPropertyRNA:
|
|||||||
type_str += " in [%s, %s]" % (range_str(self.min), range_str(self.max))
|
type_str += " in [%s, %s]" % (range_str(self.min), range_str(self.max))
|
||||||
elif self.type == "enum":
|
elif self.type == "enum":
|
||||||
if self.is_enum_flag:
|
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:
|
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):
|
if not (as_arg or as_ret):
|
||||||
# write default property, ignore function args for this
|
# write default property, ignore function args for this
|
||||||
|
@ -145,18 +145,18 @@ int BLI_utf8_invalid_strip(char *str, int length)
|
|||||||
|
|
||||||
/* compatible with BLI_strncpy, but esnure no partial utf8 chars */
|
/* 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',
|
* note: this looks to be at odd's with 'trailingBytesForUTF8',
|
||||||
* need to find out what gives here! - campbell */
|
* need to find out what gives here! - campbell */
|
||||||
static const size_t utf8_skip_data[256] = {
|
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,
|
||||||
1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
|
1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
|
||||||
1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
|
1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
|
||||||
1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,
|
1,1,1,1,1,1,1,1,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,
|
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
|
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)
|
char *BLI_strncpy_utf8(char *dst, const char *src, size_t maxncpy)
|
||||||
|
@ -348,20 +348,20 @@ EnumPropertyItem keymap_modifiers_items[] = {
|
|||||||
{0, NULL, 0, NULL, NULL}};
|
{0, NULL, 0, NULL, NULL}};
|
||||||
|
|
||||||
EnumPropertyItem operator_flag_items[] = {
|
EnumPropertyItem operator_flag_items[] = {
|
||||||
{OPTYPE_REGISTER, "REGISTER", 0, "Register", ""},
|
{OPTYPE_REGISTER, "REGISTER", 0, "Register", "Display in the info window and support the redo toolbar panel"},
|
||||||
{OPTYPE_UNDO, "UNDO", 0, "Undo", ""},
|
{OPTYPE_UNDO, "UNDO", 0, "Undo", "Push an undo event (needed for operator redo)"},
|
||||||
{OPTYPE_BLOCKING, "BLOCKING", 0, "Blocking", ""},
|
{OPTYPE_BLOCKING, "BLOCKING", 0, "Blocking", "Block anything else from using the cursor"},
|
||||||
{OPTYPE_MACRO, "MACRO", 0, "Macro", ""},
|
{OPTYPE_MACRO, "MACRO", 0, "Macro", "Use to check if an operator is a macro"},
|
||||||
{OPTYPE_GRAB_POINTER, "GRAB_POINTER", 0, "Grab Pointer", ""},
|
{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", ""},
|
{OPTYPE_PRESET, "PRESET", 0, "Preset", "Display a preset button with the operators settings"},
|
||||||
{OPTYPE_INTERNAL, "INTERNAL", 0, "Internal", ""},
|
{OPTYPE_INTERNAL, "INTERNAL", 0, "Internal", "Removes the operator from search results"},
|
||||||
{0, NULL, 0, NULL, NULL}};
|
{0, NULL, 0, NULL, NULL}};
|
||||||
|
|
||||||
EnumPropertyItem operator_return_items[] = {
|
EnumPropertyItem operator_return_items[] = {
|
||||||
{OPERATOR_RUNNING_MODAL, "RUNNING_MODAL", 0, "Running Modal", ""},
|
{OPERATOR_RUNNING_MODAL, "RUNNING_MODAL", 0, "Running Modal", "Keep the operator running with blender"},
|
||||||
{OPERATOR_CANCELLED, "CANCELLED", 0, "Cancelled", ""},
|
{OPERATOR_CANCELLED, "CANCELLED", 0, "Cancelled", "When no action has been taken, operator exits"},
|
||||||
{OPERATOR_FINISHED, "FINISHED", 0, "Finished", ""},
|
{OPERATOR_FINISHED, "FINISHED", 0, "Finished", "When the operator is complete, operator exits"},
|
||||||
{OPERATOR_PASS_THROUGH, "PASS_THROUGH", 0, "Pass Through", ""}, // used as a flag
|
{OPERATOR_PASS_THROUGH, "PASS_THROUGH", 0, "Pass Through", "Do nothing and pass the event on"}, // used as a flag
|
||||||
{0, NULL, 0, NULL, NULL}};
|
{0, NULL, 0, NULL, NULL}};
|
||||||
|
|
||||||
/* flag/enum */
|
/* flag/enum */
|
||||||
|
Loading…
Reference in New Issue
Block a user