== python api docs ==

- now that I've made syntax changes in the previous commit I moved blocks to to have sensors/actuators grouped together
- added sections to have a nice table of contents
- formatted 2 lists and links to classes

1 files changed, 166 insertions, 134 deletions

diff --git a/source/gameengine/PyDoc/bge.logic.rst b/source/gameengine/PyDoc/bge.logic.rst
index 549948c7d09..f48dc56521c 100644
--- a/source/gameengine/PyDoc/bge.logic.rst
+++ b/source/gameengine/PyDoc/bge.logic.rst
@@ -1,7 +1,10 @@
 
 Game Engine bge.logic Module
 ============================
-	
+*****
+Intro
+*****
+
 Module to access logic functions, imported automatically into the python controllers namespace.
 
 .. module:: bge.logic
@@ -14,7 +17,7 @@ Module to access logic functions, imported automatically into the python control
    # To get the game object this controller is on:
    obj = cont.owner
 
-:class:`bge.types.KX_GameObject` and :class:`bge.types.KX_Camera` or :class:`bge.types.KX_LightObject` methods are available depending on the type of object
+:class:`~bge.types.KX_GameObject` and :class:`~bge.types.KX_Camera` or :class:`bge.types.~KX_LightObject` methods are available depending on the type of object
 
 .. code-block:: python
 
@@ -30,18 +33,21 @@ Module to access logic functions, imported automatically into the python control
 
 See the sensor's reference for available methods:
 
-* :class:`bge.types.SCA_DelaySensor`
-* :class:`bge.types.SCA_JoystickSensor`
-* :class:`bge.types.SCA_KeyboardSensor`
-* :class:`bge.types.KX_MouseFocusSensor`
-* :class:`bge.types.SCA_MouseSensor`
-* :class:`bge.types.KX_NearSensor`
-* :class:`bge.types.KX_NetworkMessageSensor`
-* :class:`bge.types.SCA_PropertySensor`
-* :class:`bge.types.KX_RadarSensor`
-* :class:`bge.types.SCA_RandomSensor`
-* :class:`bge.types.KX_RaySensor`
-* :class:`bge.types.KX_TouchSensor`
+.. hlist::
+   :columns: 3
+
+   * :class:`~bge.types.KX_MouseFocusSensor`
+   * :class:`~bge.types.KX_NearSensor`
+   * :class:`~bge.types.KX_NetworkMessageSensor`
+   * :class:`~bge.types.KX_RadarSensor`
+   * :class:`~bge.types.KX_RaySensor`
+   * :class:`~bge.types.KX_TouchSensor`
+   * :class:`~bge.types.SCA_DelaySensor`
+   * :class:`~bge.types.SCA_JoystickSensor`
+   * :class:`~bge.types.SCA_KeyboardSensor`
+   * :class:`~bge.types.SCA_MouseSensor`
+   * :class:`~bge.types.SCA_PropertySensor`
+   * :class:`~bge.types.SCA_RandomSensor`
 
 You can also access actuators linked to the controller
 
@@ -56,30 +62,32 @@ You can also access actuators linked to the controller
    # Activate an actuator
    controller.activate(actuator)
 
-
 See the actuator's reference for available methods
 
-* :class:`bge.types.SCA_2DFilterActuator`
-* :class:`bge.types.BL_ActionActuator`
-* :class:`bge.types.KX_SCA_AddObjectActuator`
-* :class:`bge.types.KX_CameraActuator`
-* :class:`bge.types.KX_ConstraintActuator`
-* :class:`bge.types.KX_SCA_DynamicActuator`
-* :class:`bge.types.KX_SCA_EndObjectActuator`
-* :class:`bge.types.KX_GameActuator`
-* :class:`bge.types.KX_IpoActuator`
-* :class:`bge.types.KX_NetworkMessageActuator`
-* :class:`bge.types.KX_ObjectActuator`
-* :class:`bge.types.KX_ParentActuator`
-* :class:`bge.types.SCA_PropertyActuator`
-* :class:`bge.types.SCA_RandomActuator`
-* :class:`bge.types.KX_SCA_ReplaceMeshActuator`
-* :class:`bge.types.KX_SceneActuator`
-* :class:`bge.types.BL_ShapeActionActuator`
-* :class:`bge.types.KX_SoundActuator`
-* :class:`bge.types.KX_StateActuator`
-* :class:`bge.types.KX_TrackToActuator`
-* :class:`bge.types.KX_VisibilityActuator`
+.. hlist::
+   :columns: 3
+   
+   * :class:`~bge.types.BL_ActionActuator`
+   * :class:`~bge.types.BL_ShapeActionActuator`
+   * :class:`~bge.types.KX_CameraActuator`
+   * :class:`~bge.types.KX_ConstraintActuator`
+   * :class:`~bge.types.KX_GameActuator`
+   * :class:`~bge.types.KX_IpoActuator`
+   * :class:`~bge.types.KX_NetworkMessageActuator`
+   * :class:`~bge.types.KX_ObjectActuator`
+   * :class:`~bge.types.KX_ParentActuator`
+   * :class:`~bge.types.KX_SCA_AddObjectActuator`
+   * :class:`~bge.types.KX_SCA_DynamicActuator`
+   * :class:`~bge.types.KX_SCA_EndObjectActuator`
+   * :class:`~bge.types.KX_SCA_ReplaceMeshActuator`
+   * :class:`~bge.types.KX_SceneActuator`
+   * :class:`~bge.types.KX_SoundActuator`
+   * :class:`~bge.types.KX_StateActuator`
+   * :class:`~bge.types.KX_TrackToActuator`
+   * :class:`~bge.types.KX_VisibilityActuator`
+   * :class:`~bge.types.SCA_2DFilterActuator`
+   * :class:`~bge.types.SCA_PropertyActuator`
+   * :class:`~bge.types.SCA_RandomActuator`
 
 Most logic brick's methods are accessors for the properties available in the logic buttons.
 Consult the logic bricks documentation for more information on how each logic brick works.
@@ -99,16 +107,28 @@ Matricies as used by the game engine are **row major**
 
 :class:`bge.types.KX_Camera` has some examples using matricies.
 
+*********
+Variables
+*********
 
 .. data:: globalDict
 
    A dictionary that is saved between loading blend files so you can use it to store inventory and other variables you want to store between scenes and blend files.
    It can also be written to a file and loaded later on with the game load/save actuators.
 
-   .. note:: only python built in types such as int/string/bool/float/tuples/lists can be saved, GameObjects, Actuators etc will not work as expectred.
+   .. note:: only python built in types such as int/string/bool/float/tuples/lists can be saved, GameObjects, Actuators etc will not work as expected.
+
+.. data:: keyboard
+
+   The current keyboard wrapped in an :class:`~bge.types.SCA_PythonKeyboard` object.
 
-.. data:: keyboard:		The current keyboard wrapped in an SCA_PythonKeyboard object.
-.. data:: mouse:			The current mouse wrapped in an SCA_PythonMouse object.
+.. data:: mouse
+
+   The current mouse wrapped in an :class:`~bge.types.SCA_PythonMouse` object.
+
+*****************
+General functions
+*****************
 
 .. function:: getCurrentController()
 
@@ -258,15 +278,9 @@ Matricies as used by the game engine are **row major**
 
    Loads bge.logic.globalDict from a file.
 
-
+*****************
 Utility functions
-
-.. function:: getAverageFrameRate()
-
-   Gets the estimated average framerate
-   
-   :return: The estimed average framerate in frames per second
-   :rtype: float
+*****************
 
 .. function:: expandPath(path)
 
@@ -283,6 +297,12 @@ Utility functions
    :return: The converted string
    :rtype: string
 
+.. function:: getAverageFrameRate()
+
+   Gets the estimated average framerate
+   
+   :return: The estimed average framerate in frames per second
+   :rtype: float
 
 .. function:: getBlendFileList(path = "//")
 
@@ -293,17 +313,17 @@ Utility functions
    :return: A list of filenames, with no directory prefix
    :rtype: list
 
-.. function:: PrintGLInfo()
-
-   Prints GL Extension Info into the console
-
 .. function:: getRandomFloat()
 
    Returns a random floating point value in the range [0 - 1)
 
-=========
+.. function:: PrintGLInfo()
+
+   Prints GL Extension Info into the console
+   
+*********
 Constants
-=========
+*********
 
 .. data:: KX_TRUE
 
@@ -313,6 +333,10 @@ Constants
 
    False value used by some modules.
 
+=======
+Sensors
+======= 
+
 ---------------
 Property Sensor
 ---------------
@@ -337,6 +361,49 @@ Property Sensor
 
    Activate when the expression matches
 
+------------
+Radar Sensor
+------------
+
+See :class:`bge.types.KX_RadarSensor`
+
+.. data:: KX_RADAR_AXIS_POS_X
+.. data:: KX_RADAR_AXIS_POS_Y
+.. data:: KX_RADAR_AXIS_POS_Z
+.. data:: KX_RADAR_AXIS_NEG_X
+.. data:: KX_RADAR_AXIS_NEG_Y
+.. data:: KX_RADAR_AXIS_NEG_Z
+
+----------
+Ray Sensor
+----------
+
+See :class:`bge.types.KX_RaySensor`
+
+.. data:: KX_RAY_AXIS_POS_X
+.. data:: KX_RAY_AXIS_POS_Y
+.. data:: KX_RAY_AXIS_POS_Z
+.. data:: KX_RAY_AXIS_NEG_X
+.. data:: KX_RAY_AXIS_NEG_Y
+.. data:: KX_RAY_AXIS_NEG_Z
+
+
+=========
+Actuators
+=========
+
+---------------
+Action Actuator
+---------------
+
+See :class:`bge.types.BL_ActionActuator`
+
+.. data:: KX_ACTIONACT_PLAY
+.. data:: KX_ACTIONACT_FLIPPER
+.. data:: KX_ACTIONACT_LOOPSTOP
+.. data:: KX_ACTIONACT_LOOPEND
+.. data:: KX_ACTIONACT_PROPERTY
+
 -------------------
 Constraint Actuator
 -------------------
@@ -434,6 +501,30 @@ See :class:`bge.types.KX_ConstraintActuator`
 .. data:: KX_ACT_CONSTRAINT_NORMAL
 .. data:: KX_ACT_CONSTRAINT_PERMANENT
 
+----------------
+Dynamic Actuator
+----------------
+
+See :class:`bge.types.KX_SCA_DynamicActuator`
+
+.. data:: KX_DYN_RESTORE_DYNAMICS
+.. data:: KX_DYN_DISABLE_DYNAMICS
+.. data:: KX_DYN_ENABLE_RIGID_BODY
+.. data:: KX_DYN_DISABLE_RIGID_BODY
+.. data:: KX_DYN_SET_MASS
+
+-------------
+Game Actuator
+-------------
+
+See :class:`bge.types.KX_GameActuator`
+
+.. data:: KX_GAME_LOAD
+.. data:: KX_GAME_START
+.. data:: KX_GAME_RESTART
+.. data:: KX_GAME_QUIT
+.. data:: KX_GAME_SAVECFG
+.. data:: KX_GAME_LOADCFG
 
 ------------
 IPO Actuator
@@ -448,6 +539,13 @@ See :class:`bge.types.KX_IpoActuator`
 .. data:: KX_IPOACT_LOOPEND
 .. data:: KX_IPOACT_FROM_PROP
 
+---------------
+Parent Actuator
+---------------
+
+.. data:: KX_PARENT_REMOVE
+.. data:: KX_PARENT_SET
+
 --------------------
 Random Distributions
 --------------------
@@ -465,17 +563,20 @@ See :class:`bge.types.SCA_RandomActuator`
 .. data:: KX_RANDOMACT_FLOAT_NORMAL
 .. data:: KX_RANDOMACT_FLOAT_NEGATIVE_EXPONENTIAL
 
----------------
-Action Actuator
----------------
+--------------
+Scene Actuator
+--------------
 
-See :class:`bge.types.BL_ActionActuator`
+See :class:`bge.types.KX_SceneActuator`
 
-.. data:: KX_ACTIONACT_PLAY
-.. data:: KX_ACTIONACT_FLIPPER
-.. data:: KX_ACTIONACT_LOOPSTOP
-.. data:: KX_ACTIONACT_LOOPEND
-.. data:: KX_ACTIONACT_PROPERTY
+.. data:: KX_SCENE_RESTART
+.. data:: KX_SCENE_SET_SCENE
+.. data:: KX_SCENE_SET_CAMERA
+.. data:: KX_SCENE_ADD_FRONT_SCENE
+.. data:: KX_SCENE_ADD_BACK_SCENE
+.. data:: KX_SCENE_REMOVE_SCENE
+.. data:: KX_SCENE_SUSPEND
+.. data:: KX_SCENE_RESUME
 
 --------------
 Sound Actuator
@@ -490,71 +591,9 @@ See :class:`bge.types.KX_SoundActuator`
 .. data:: KX_SOUNDACT_LOOPBIDIRECTIONAL
 .. data:: KX_SOUNDACT_LOOPBIDIRECTIONAL_STOP
 
-------------
-Radar Sensor
-------------
-
-See :class:`bge.types.KX_RadarSensor`
-
-.. data:: KX_RADAR_AXIS_POS_X
-.. data:: KX_RADAR_AXIS_POS_Y
-.. data:: KX_RADAR_AXIS_POS_Z
-.. data:: KX_RADAR_AXIS_NEG_X
-.. data:: KX_RADAR_AXIS_NEG_Y
-.. data:: KX_RADAR_AXIS_NEG_Z
-
-----------
-Ray Sensor
-----------
-
-See :class:`bge.types.KX_RaySensor`
-
-.. data:: KX_RAY_AXIS_POS_X
-.. data:: KX_RAY_AXIS_POS_Y
-.. data:: KX_RAY_AXIS_POS_Z
-.. data:: KX_RAY_AXIS_NEG_X
-.. data:: KX_RAY_AXIS_NEG_Y
-.. data:: KX_RAY_AXIS_NEG_Z
-
-----------------
-Dynamic Actuator
-----------------
-
-See :class:`bge.types.KX_SCA_DynamicActuator`
-
-.. data:: KX_DYN_RESTORE_DYNAMICS
-.. data:: KX_DYN_DISABLE_DYNAMICS
-.. data:: KX_DYN_ENABLE_RIGID_BODY
-.. data:: KX_DYN_DISABLE_RIGID_BODY
-.. data:: KX_DYN_SET_MASS
-
--------------
-Game Actuator
--------------
-
-See :class:`bge.types.KX_GameActuator`
-
-.. data:: KX_GAME_LOAD
-.. data:: KX_GAME_START
-.. data:: KX_GAME_RESTART
-.. data:: KX_GAME_QUIT
-.. data:: KX_GAME_SAVECFG
-.. data:: KX_GAME_LOADCFG
-
---------------
-Scene Actuator
---------------
-
-See :class:`bge.types.KX_SceneActuator`
-
-.. data:: KX_SCENE_RESTART
-.. data:: KX_SCENE_SET_SCENE
-.. data:: KX_SCENE_SET_CAMERA
-.. data:: KX_SCENE_ADD_FRONT_SCENE
-.. data:: KX_SCENE_ADD_BACK_SCENE
-.. data:: KX_SCENE_REMOVE_SCENE
-.. data:: KX_SCENE_SUSPEND
-.. data:: KX_SCENE_RESUME
+=======
+Various
+=======
 
 ------------
 Input Status
@@ -638,13 +677,6 @@ See :class:`bge.types.KX_StateActuator`
 .. data:: RAS_2DFILTER_SHARPEN
 .. data:: RAS_2DFILTER_SOBEL
 
----------------
-Parent Actuator
----------------
-
-.. data:: KX_PARENT_REMOVE
-.. data:: KX_PARENT_SET
-
 ------
 Shader
 ------