From dba99b544bb9561405c6305e8fb90d369526407f Mon Sep 17 00:00:00 2001
From: Luca Bonavita <mindrones@gmail.com>
Date: Fri, 11 Jun 2010 22:41:13 +0000
Subject: [PATCH] == 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)
---
 source/blender/python/doc/sphinx_doc_gen.py | 27 ++++++++++++++-------
 source/gameengine/PyDoc/bge.types.rst       |  2 +-
 2 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/source/blender/python/doc/sphinx_doc_gen.py b/source/blender/python/doc/sphinx_doc_gen.py
index fd6cf74691e..8f823ae238f 100644
--- a/source/blender/python/doc/sphinx_doc_gen.py
+++ b/source/blender/python/doc/sphinx_doc_gen.py
@@ -54,6 +54,9 @@ EXAMPLE_SET_USED = set()
 _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 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
     
     if type(descr) == GetSetDescriptorType:
         fw(ident + ".. attribute:: %s\n\n" % identifier)
@@ -154,8 +157,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" % identifier)
-
+        fw(ident + "   " + undocumented_message)
 
 def pyprop2sphinx(ident, fw, identifier, py_prop):
     '''
@@ -641,10 +643,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("__")]
 
@@ -679,8 +681,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
+            else:
+                operator_description = op.description
+
+            fw("   %s\n\n" % operator_description)
             for prop in op.args:
                 write_param("   ", fw, prop)
             if op.args:
diff --git a/source/gameengine/PyDoc/bge.types.rst b/source/gameengine/PyDoc/bge.types.rst
index 1800ea0db2d..935d3e7e00e 100644
--- a/source/gameengine/PyDoc/bge.types.rst
+++ b/source/gameengine/PyDoc/bge.types.rst
@@ -2309,7 +2309,7 @@ Game Engine  bge.types Module
       :return: mesh proxy
       :rtype: :class:`MeshProxy`
 
-.. class:: KX_PolygonMaterial
+.. class:: KX_PolygonMaterial(PyObjectPlus)
 
    This is the interface to materials in the game engine.