From 8d3a5a8b0aebb8b897e4e01d517720196e0b075b Mon Sep 17 00:00:00 2001 From: Luca Bonavita Date: Tue, 15 Jun 2010 02:06:01 +0000 Subject: == 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 --- source/blender/python/doc/sphinx_doc_gen.py | 39 ++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 12 deletions(-) (limited to 'source/blender/python/doc/sphinx_doc_gen.py') diff --git a/source/blender/python/doc/sphinx_doc_gen.py b/source/blender/python/doc/sphinx_doc_gen.py index 8f823ae238f..4640ba4c1ef 100644 --- a/source/blender/python/doc/sphinx_doc_gen.py +++ b/source/blender/python/doc/sphinx_doc_gen.py @@ -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 @@ -54,10 +54,19 @@ EXAMPLE_SET_USED = set() _BPY_STRUCT_FAKE = "bpy_struct" _BPY_FULL_REBUILD = False -undocumented_message = "Undocumented (`suggest a description " \ - "`_)\n\n" +def undocumented_message(module_name, type_name, identifier): + message = "Undocumented (`contribute " \ + "`_)\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 @@ 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: @@ -76,6 +85,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"): @@ -131,14 +143,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_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 @@ 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. ''' @@ -157,7 +171,8 @@ 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_message) + fw(ident + " " + undocumented_message(module_name, type_name, identifier)) + def pyprop2sphinx(ident, fw, identifier, py_prop): ''' @@ -221,7 +236,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): @@ -249,7 +264,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: @@ -685,7 +700,7 @@ def rna2sphinx(BASEPATH): # 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 -- cgit v1.2.3