Cr8-xyz/blender
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki 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
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