[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [29458] trunk/blender/source/blender/ python: == python api docs ==
Luca Bonavita
mindrones at gmail.com
Tue Jun 15 04:06:03 CEST 2010
Revision: 29458
http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=29458
Author: mindrones
Date: 2010-06-15 04:06:01 +0200 (Tue, 15 Jun 2010)
Log Message:
-----------
== python api docs ==
* source/blender/python/doc/sphinx_doc_gen.py:
changed the "undocumented" message so that it still links to
http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute
but uses flags in the url to help documenting.
Example: http://www.blender.org/documentation/250PythonDoc/bpy.ops.node.html#bpy.ops.node.link
click on "contribute", the new section has title "bpy.ops.node.link" and a howto message is shown
* source/blender/python/intern/bpy.c:
fixed a typo
Modified Paths:
--------------
trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
trunk/blender/source/blender/python/intern/bpy.c
Modified: trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
===================================================================
--- trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-06-15 01:28:17 UTC (rev 29457)
+++ trunk/blender/source/blender/python/doc/sphinx_doc_gen.py 2010-06-15 02:06:01 UTC (rev 29458)
@@ -24,7 +24,7 @@
./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
@@ -54,10 +54,19 @@
_BPY_STRUCT_FAKE = "bpy_struct"
_BPY_FULL_REBUILD = False
-undocumented_message = "Undocumented (`suggest a description " \
- "<http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute>`_)\n\n"
+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§ion=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:
@@ -66,9 +75,9 @@
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:
@@ -76,6 +85,9 @@
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"):
@@ -131,14 +143,15 @@
def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):
+
doc = descr.__doc__
if not doc:
- doc = undocumented_message
+ 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")
@@ -146,7 +159,8 @@
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.
'''
@@ -157,8 +171,9 @@
fw("\n")
else:
fw(ident + ".. function:: %s()\n\n" % identifier)
- fw(ident + " " + undocumented_message)
+ fw(ident + " " + undocumented_message(module_name, type_name, identifier))
+
def pyprop2sphinx(ident, fw, identifier, py_prop):
'''
python property to sphinx
@@ -221,7 +236,7 @@
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):
@@ -249,7 +264,7 @@
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:
@@ -685,7 +700,7 @@
# 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
+ operator_description = undocumented_message('bpy.ops',op.module_name,op.func_name)
else:
operator_description = op.description
Modified: trunk/blender/source/blender/python/intern/bpy.c
===================================================================
--- trunk/blender/source/blender/python/intern/bpy.c 2010-06-15 01:28:17 UTC (rev 29457)
+++ trunk/blender/source/blender/python/intern/bpy.c 2010-06-15 02:06:01 UTC (rev 29458)
@@ -75,7 +75,7 @@
static char bpy_blend_paths_doc[] =
".. function:: blend_paths(absolute=False)\n"
"\n"
-" Returns a list of paths assosiated with this blend file.\n"
+" Returns a list of paths associated with this blend file.\n"
"\n"
" :arg absolute: When true the paths returned are made absolute.\n"
" :type absolute: boolean\n"
More information about the Bf-blender-cvs
mailing list