archive/blender-archive
Archived
1
1
Fork 0
Code Pull Requests Packages Activity

Merged changes in the trunk up to revision 29550.

Browse Source
This commit is contained in:
Tamito Kajiyama
2010-06-18 22:53:49 +00:00
parent df0b629e24 615af47559
commit 4d141cf808
182 changed files with 2370 additions and 1661 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
source/blender/python/doc/sphinx_doc_gen.py
View File

@@ -24,7 +24,7 @@ run this script from blenders root path once you have compiled blender
./blender.bin -b -P /b/source/blender/python/doc/sphinx_doc_gen.py
This will generate python files in "./source/blender/python/doc/sphinx-in"
Generate html docs by running...
Generate html docs by running...
sphinx-build source/blender/python/doc/sphinx-in source/blender/python/doc/sphinx-out
@@ -55,7 +55,19 @@ EXAMPLE_SET_USED = set()
_BPY_STRUCT_FAKE = "bpy_struct"
_BPY_FULL_REBUILD = False
def undocumented_message(module_name, type_name, identifier):
message = "Undocumented (`contribute " \
"<http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute" \
"?action=edit&section=new&preload=Dev:2.5/Py/API/Documentation/Contribute/Howto-message" \
"&preloadtitle=%s.%s.%s>`_)\n\n" % (module_name, type_name, identifier)
return message
def range_str(val):
'''
Converts values to strings for the range directive.
(unused function it seems)
'''
if val < -10000000: return '-inf'
if val > 10000000: return 'inf'
if type(val)==float:
@@ -64,9 +76,9 @@ def range_str(val):
return str(val)
def write_example_ref(ident, fw, example_id, ext=".py"):
def write_example_ref(ident, fw, example_id, ext="py"):
if example_id in EXAMPLE_SET:
fw("%s.. literalinclude:: ../examples/%s%s\n\n" % (ident, example_id, ext))
fw("%s.. literalinclude:: ../examples/%s.%s\n\n" % (ident, example_id, ext))
EXAMPLE_SET_USED.add(example_id)
else:
if bpy.app.debug:
@@ -74,6 +86,9 @@ def write_example_ref(ident, fw, example_id, ext=".py"):
def write_indented_lines(ident, fn, text, strip=True):
'''
Apply same indentation to all lines in a multilines text.
'''
if text is None:
return
for l in text.split("\n"):
@@ -129,14 +144,15 @@ def pyfunc2sphinx(ident, fw, identifier, py_func, is_class=True):
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
doc = descr.__doc__
if not doc:
doc = "Undocumented"
doc = undocumented_message(module_name, type_name, identifier)
if type(descr) == GetSetDescriptorType:
fw(ident + ".. attribute:: %s\n\n" % identifier)
write_indented_lines(ident + " ", fw, doc, False)
elif type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
elif type(descr) == MethodDescriptorType: # GetSetDescriptorType's are not documented yet
write_indented_lines(ident, fw, doc, False)
else:
raise TypeError("type was not GetSetDescriptorType or MethodDescriptorType")
@@ -144,7 +160,8 @@ def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
write_example_ref(ident, fw, module_name + "." + type_name + "." + identifier)
fw("\n")
def py_c_func2sphinx(ident, fw, identifier, py_func, is_class=True):
def py_c_func2sphinx(ident, fw, module_name, type_name, identifier, py_func, is_class=True):
'''
c defined function to sphinx.
'''
@@ -155,7 +172,7 @@ def py_c_func2sphinx(ident, fw, identifier, py_func, is_class=True):
fw("\n")
else:
fw(ident + ".. function:: %s()\n\n" % identifier)
fw(ident + " Undocumented function.\n\n")
fw(ident + " " + undocumented_message(module_name, type_name, identifier))
def pyprop2sphinx(ident, fw, identifier, py_prop):
@@ -220,7 +237,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
elif value_type in (types.BuiltinMethodType, types.BuiltinFunctionType): # both the same at the moment but to be future proof
# note: can't get args from these, so dump the string as is
# this means any module used like this must have fully formatted docstrings.
py_c_func2sphinx("", fw, attribute, value, is_class=False)
py_c_func2sphinx("", fw, module_name, module, attribute, value, is_class=False)
elif value_type == type:
classes.append((attribute, value))
elif value_type in (bool, int, float, str, tuple):
@@ -248,7 +265,7 @@ def pymodule2sphinx(BASEPATH, module_name, module, title):
descr_items = [(key, descr) for key, descr in sorted(value.__dict__.items()) if not key.startswith("__")]
for key, descr in descr_items:
if type(descr) == MethodDescriptorType: # GetSetDescriptorType, GetSetDescriptorType's are not documented yet
if type(descr) == MethodDescriptorType: # GetSetDescriptorType's are not documented yet
py_descr2sphinx(" ", fw, descr, module_name, type_name, key)
for key, descr in descr_items:
@@ -321,6 +338,7 @@ def rna2sphinx(BASEPATH):
fw(" \n")
fw(" The following areas are subject to change.\n")
fw(" * operator names and arguments\n")
fw(" * render api\n")
fw(" * function calls with the data api (any function calls with values accessed from bpy.data), including functions for importing and exporting meshes\n")
fw(" * class registration (Operator, Panels, Menus, Headers)\n")
fw(" * modules: bpy.props, blf)\n")
@@ -653,10 +671,10 @@ def rna2sphinx(BASEPATH):
if subclass_ids:
fw("subclasses --- \n" + ", ".join([(":class:`%s`" % s) for s in sorted(subclass_ids)]) + "\n\n")
fw(".. class:: %s\n" % _BPY_STRUCT_FAKE)
fw("\n")
fw(" built-in base class for all classes in bpy.types, note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n" % _BPY_STRUCT_FAKE)
fw("\n")
fw(".. class:: %s\n\n" % _BPY_STRUCT_FAKE)
fw(" built-in base class for all classes in bpy.types.\n\n")
fw(" .. note::\n\n")
fw(" Note that bpy.types.%s is not actually available from within blender, it only exists for the purpose of documentation.\n\n" % _BPY_STRUCT_FAKE)
descr_items = [(key, descr) for key, descr in sorted(bpy.types.Struct.__bases__[0].__dict__.items()) if not key.startswith("__")]
@@ -691,8 +709,15 @@ def rna2sphinx(BASEPATH):
args_str = ", ".join([prop.get_arg_default(force=True) for prop in op.args])
fw(".. function:: %s(%s)\n\n" % (op.func_name, args_str))
if op.description:
fw(" %s\n\n" % op.description)
# if the description isn't valid, we output the standard warning
# with a link to the wiki so that people can help
if not op.description or op.description == "(undocumented operator)":
operator_description = undocumented_message('bpy.ops',op.module_name,op.func_name)
else:
operator_description = op.description
fw(" %s\n\n" % operator_description)
for prop in op.args:
write_param(" ", fw, prop)
if op.args: