[Bf-blender-cvs] SVN commit: /data/svn/bf-blender [29418] trunk/blender/source: == python api docs ==

[Luca Bonavita]

Revision: 29418
          http://projects.blender.org/plugins/scmsvn/viewcvs.php?view=rev&root=bf-blender&revision=29418
Author:   mindrones
Date:     2010-06-12 00:41:13 +0200 (Sat, 12 Jun 2010)

Log Message:
-----------
== python api docs ==

* source/gameengine/PyDoc/bge.types.rst:
  KX_PolygonMaterial was missing the parent class indication (PyObjectPlus)

* source/blender/python/doc/sphinx_doc_gen.py:
  * unified all the "undocumented" descriptions, like
    http://www.blender.org/documentation/250PythonDoc/bpy.ops.anim.html#bpy.ops.anim.keyframe_delete_button
    so that it will be easy for Alex to CCS 'em and also now people will have a link to contribute descriptions,
    see http://wiki.blender.org/index.php/Dev:2.5/Py/API/Documentation/Contribute
  * moved the note about bpy_struct not being available in the api
    in a proper note directive, so that it's more evident
    (I didn't see it at first)

Modified Paths:
--------------
    trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
    trunk/blender/source/gameengine/PyDoc/bge.types.rst

Modified: trunk/blender/source/blender/python/doc/sphinx_doc_gen.py
===================================================================
--- trunk/blender/source/blender/python/doc/sphinx_doc_gen.py	2010-06-11 21:53:10 UTC (rev 29417)
+++ trunk/blender/source/blender/python/doc/sphinx_doc_gen.py	2010-06-11 22:41:13 UTC (rev 29418)
@@ -54,6 +54,9 @@
 _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 range_str(val):
     if val < -10000000:	return '-inf'
     if val >  10000000:	return 'inf'
@@ -130,7 +133,7 @@
 def py_descr2sphinx(ident, fw, descr, module_name, type_name, identifier):    
     doc = descr.__doc__
     if not doc:
-        doc = "Undocumented"
+        doc = undocumented_message
     
     if type(descr) == GetSetDescriptorType:
         fw(ident + ".. attribute:: %s\n\n" % identifier)
@@ -154,9 +157,8 @@
         fw("\n")
     else:
         fw(ident + ".. function:: %s()\n\n" % identifier)
-        fw(ident + "   Undocumented function.\n\n" % identifier)
+        fw(ident + "   " + undocumented_message)
 
-
 def pyprop2sphinx(ident, fw, identifier, py_prop):
     '''
     python property to sphinx
@@ -641,10 +643,10 @@
         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("__")]
 
@@ -679,8 +681,15 @@
 
             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
+            else:
+                operator_description = op.description
+
+            fw("   %s\n\n" % operator_description)
             for prop in op.args:
                 write_param("   ", fw, prop)
             if op.args:

Modified: trunk/blender/source/gameengine/PyDoc/bge.types.rst
===================================================================
--- trunk/blender/source/gameengine/PyDoc/bge.types.rst	2010-06-11 21:53:10 UTC (rev 29417)
+++ trunk/blender/source/gameengine/PyDoc/bge.types.rst	2010-06-11 22:41:13 UTC (rev 29418)
@@ -2309,7 +2309,7 @@
       :return: mesh proxy
       :rtype: :class:`MeshProxy`
 
-.. class:: KX_PolygonMaterial
+.. class:: KX_PolygonMaterial(PyObjectPlus)
 
    This is the interface to materials in the game engine.