[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [40237] trunk/blender: - include enum names and descriptions in sphinx generated documentation
Campbell Barton
ideasman42 at gmail.com
Thu Sep 15 18:15:24 CEST 2011
Revision: 40237
http://projects.blender.org/scm/viewvc.php?view=rev&root=bf-blender&revision=40237
Author: campbellbarton
Date: 2011-09-15 16:15:24 +0000 (Thu, 15 Sep 2011)
Log Message:
-----------
- include enum names and descriptions in sphinx generated documentation
- add descriptions for operator bl_options
Modified Paths:
--------------
trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py
trunk/blender/doc/python_api/sphinx_doc_gen.py
trunk/blender/doc/python_api/sphinx_doc_gen.sh
trunk/blender/release/scripts/modules/rna_info.py
trunk/blender/source/blender/blenlib/intern/string_utf8.c
trunk/blender/source/blender/makesrna/intern/rna_wm.c
Modified: trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py
===================================================================
--- trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py 2011-09-15 16:09:42 UTC (rev 40236)
+++ trunk/blender/doc/python_api/examples/bpy.types.ID.user_clear.1.py 2011-09-15 16:15:24 UTC (rev 40237)
@@ -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.
"""
Modified: trunk/blender/doc/python_api/sphinx_doc_gen.py
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.py 2011-09-15 16:09:42 UTC (rev 40236)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.py 2011-09-15 16:15:24 UTC (rev 40237)
@@ -76,7 +76,7 @@
"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 @@
"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 @@
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 @@
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 @@
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 @@
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:
Modified: trunk/blender/doc/python_api/sphinx_doc_gen.sh
===================================================================
--- trunk/blender/doc/python_api/sphinx_doc_gen.sh 2011-09-15 16:09:42 UTC (rev 40236)
+++ trunk/blender/doc/python_api/sphinx_doc_gen.sh 2011-09-15 16:15:24 UTC (rev 40237)
@@ -9,7 +9,11 @@
# disable for testing
DO_UPLOAD=true
+DO_EXE_BLENDER=true
+DO_OUT_HTML=true
+DO_OUT_PDF=true
+
BLENDER="./blender.bin"
SSH_USER="ideasman42"
SSH_HOST=$SSH_USER"@emo.blender.org"
@@ -36,28 +40,39 @@
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 @@
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
Modified: trunk/blender/release/scripts/modules/rna_info.py
===================================================================
--- trunk/blender/release/scripts/modules/rna_info.py 2011-09-15 16:09:42 UTC (rev 40236)
+++ trunk/blender/release/scripts/modules/rna_info.py 2011-09-15 16:15:24 UTC (rev 40237)
@@ -207,7 +207,7 @@
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 @@
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
Modified: trunk/blender/source/blender/blenlib/intern/string_utf8.c
===================================================================
--- trunk/blender/source/blender/blenlib/intern/string_utf8.c 2011-09-15 16:09:42 UTC (rev 40236)
+++ trunk/blender/source/blender/blenlib/intern/string_utf8.c 2011-09-15 16:15:24 UTC (rev 40237)
@@ -145,18 +145,18 @@
/* 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)
Modified: trunk/blender/source/blender/makesrna/intern/rna_wm.c
===================================================================
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-blender-cvs
mailing list