feat: updated doc structure

docs/source/api/image.rst

@@ -1,5 +1,5 @@
-image
-=====
+Images Overview
+===============
 
 Made of pixels and used by codea for drawing to the screen and texturing meshes
 
@@ -16,6 +16,9 @@ Made of pixels and used by codea for drawing to the screen and texturing meshes
       sprite(img, WIDTH/2, HEIGHT/2)
    end
 
+Image
+=====
+
 .. lua:class:: image
 
    .. lua:staticmethod:: image(width, height, [hasMips = false, numLayers = 1, format = image.rgba, depthFormat = none])

docs/source/api/input.rst

@@ -12,11 +12,11 @@ Touches
 
    Represents a single touch over time. Generated in response to touch events by the device in response to user interactions
 
-   .. attribute:: id: number
+   .. lua:attribute:: id: number
 
       An id that can be used to uniquely identify the touch
 
-   .. attribute:: state: enum
+   .. lua:attribute:: state: enum
 
       The current state of the touch, can be:
 
@@ -25,7 +25,7 @@ Touches
       * ``ENDED`` - the touch ended this frame
       * ``CANCELLED`` - the touch was cancelled (usually by another view or gesture recognizer)
 
-   .. attribute:: type: enum 
+   .. lua:attribute:: type: enum 
 
       The type of touch, can be:
 
@@ -34,75 +34,75 @@ Touches
       * ``touch.pencil`` - a touch resulting from the pencil
       * ``touch.pointer`` - a touch resulting from a button based device
 
-   .. attribute:: x: number
+   .. lua:attribute:: x: number
 
       The x position of the touch (in screen coordinates)
 
-   .. attribute:: y: number
+   .. lua:attribute:: y: number
 
       The y position of the touch (in screen coordinates)
 
-   .. attribute:: prevX: number
+   .. lua:attribute:: prevX: number
 
       The previous x position of the touch (in screen coordinates)
 
-   .. attribute:: prevY: number
+   .. lua:attribute:: prevY: number
 
       The previous y position of the touch (in screen coordinates)
 
-   .. attribute:: deltaX: number
+   .. lua:attribute:: deltaX: number
 
       The x position delta of the touch (in screen coordinates)
 
-   .. attribute:: deltaY: number
+   .. lua:attribute:: deltaY: number
 
       The y position delta of the touch (in screen coordinates)
 
-   .. attribute:: pos: vec2
+   .. lua:attribute:: pos: vec2
 
       The position of the touch (in screen coordinates) as a vector
 
-   .. attribute:: prevPos: vec2
+   .. lua:attribute:: prevPos: vec2
 
       The previous position of the touch (in screen coordinates) as a vector
 
-   .. attribute:: delta: number
+   .. lua:attribute:: delta: number
 
       The position delta of the touch (in screen coordinates) as a vector
 
-   .. attribute:: force: number
+   .. lua:attribute:: force: number
 
       The amount of force being applied (only applies to pencil type touches)
 
-   .. attribute:: maxForce: number
+   .. lua:attribute:: maxForce: number
 
       The maximum amount of force that can be applied (only applies to pencil type touches)
 
-   .. attribute:: timestamp: number  
+   .. lua:attribute:: timestamp: number  
 
       The time when this touch event occured (only applies to pencil type touches)
 
-   .. attribute:: azimuth: number
+   .. lua:attribute:: azimuth: number
 
       The azimuth angle of the pencil (only applies to pencil type touches)
 
-   .. attribute:: altitude: number
+   .. lua:attribute:: altitude: number
 
       The altitude angle of the pencil
 
-   .. attribute:: radiusTolerance: number
+   .. lua:attribute:: radiusTolerance: number
 
       The amount the estimated radius can vary due to hardware tolerances
 
-   .. attribute:: radius: number
+   .. lua:attribute:: radius: number
 
       The estimated radius of the touch
 
-   .. attribute:: precisePos: vec2
+   .. lua:attribute:: precisePos: vec2
 
       The precise location of the touch (if available)
 
-   .. attribute:: precisePrevPos: vec2
+   .. lua:attribute:: precisePrevPos: vec2
 
       The previous precise location of the touch (if available)
 

docs/source/api/math_types.rst

@@ -1,31 +1,40 @@
 math types
 ==========
 
-vec2
-####
+2D Vectors
+##########
 
 .. lua:class:: vec2
 
-   .. lua:staticmethod:: vec2(x)
-                         vec2(x, y)
+   This type represents a 2D vector. Most mathematical operators such as equality, addition, subtraction, multiplication and division are provided, so you can use ``vec2`` data types similarly to how you use numerical types. In addition there are a number of methods, such as ``v:dot( vec2 )`` that can be called on vec2 types.
 
-      Create a new ``vec2`` by setting both values at once or each one individually
+   :param x: Initial x value of the vector
+   :type x: number
+   :param y: Initial y value of the vector
+   :type y: number
 
-   .. lua:staticmethod:: min(v1, v2)
-
-      Return a ``vec2`` containing the component-wise minimum of two vectors
-
-   .. lua:staticmethod:: max(v1, v2)
+   :syntax:
+      .. code-block:: lua
 
-      Return a ``vec2`` containing the component-wise maximum two vectors
+         v = vec2(1, 2)
+         v = vec2(1) -- set both x and y to 1
+         v = vec2() -- set both x and y to 0
 
    .. lua:attribute:: x: number
 
       The x component of this vector
 
    .. lua:attribute:: y: number
 
-      The y component of this vector
+      The y component of this vector      
+
+   .. lua:staticmethod:: min(v1, v2)
+
+      Return a ``vec2`` containing the component-wise minimum of two vectors
+
+   .. lua:staticmethod:: max(v1, v2)
+
+      Return a ``vec2`` containing the component-wise maximum two vectors
 
    .. lua:attribute:: length: number
 
@@ -91,8 +100,8 @@ vec2
 
       Calculate the oriented angle between this vector and another, between -pi and pi
 
-vec3
-####
+3D Vectors
+##########
 
 .. lua:class:: vec3
 
@@ -173,8 +182,8 @@ vec3
 
       Unpack this vector as multiple number values
 
-vec4
-####
+4D Vectors
+##########
 
 .. lua:class:: vec4
 
@@ -255,7 +264,7 @@ vec4
 
       Unpack this vector as multiple number values
 
-vector swizzling
+Vector Swizzling
 ################
 
 ``vec2``, ``vec3`` and ``vec4`` support swizzling, which allows you to access and manipulate their components in a variety of ways
@@ -276,8 +285,8 @@ vector swizzling
 
 
 
-quat
-####
+Quaternions
+###########
 
 .. lua:class:: quat
 
@@ -356,8 +365,8 @@ quat
 
       :return: a normalized copy of this quaternion
 
-mat2
-####
+2x2 Matrix
+##########
 
 .. lua:class:: mat2
 
@@ -400,8 +409,8 @@ mat2
       :rtype: vec2
 
 
-mat3
-####
+3x3 Matrix
+##########
 
 .. lua:class:: mat3
 
@@ -444,8 +453,8 @@ mat3
       :rtype: vec3
 
 
-mat4
-####
+4x4 Matrix
+##########
 
 .. lua:class:: mat4
 
@@ -503,8 +512,8 @@ mat4
       :return: the column at a given ``index`` (starting at 1)
       :rtype: vec3
 
-aabb
-####
+Axis-Aligned Bounding Box (AABB)
+################################
 
 .. lua:module:: bounds
 

docs/source/api/motion.rst

@@ -1,9 +1,12 @@
-motion
-======
+Motion Overview
+===============
 
-   Exposes Core Motion functionalities such as accessing the device's accelerometer, gyroscope, and magnetometer data.
+Exposes Core Motion functionalities such as accessing the device's accelerometer, gyroscope, and magnetometer data.
+
+Tracking of motion metrics can impact performance and battery drain. Use this feature judiciously to avoid negatively affecting the user experience.
 
-   Tracking of motion metrics can impact performance and battery drain. Use this feature judiciously to avoid negatively affecting the user experience.
+Motion
+======
 
 .. lua:module:: motion
 
@@ -61,38 +64,53 @@ motion
 
    The heading in degrees relative to the current reference frame.
 
+Device Orientation
+==================
+
 .. lua:class:: attitude
 
-   .. lua:attribute:: pitch: number
+   Represents a measurement of your device attitude. This orientation of a body relative to a given frame of reference.
 
-      The pitch of the device, in radians.
+   You can set ``motion.attitude.referenceFrame`` to specify the frame of reference in which the attitude is expressed.
 
-   .. lua:attribute:: yaw: number
+   The value can be one of the following ``motion.referenceFrame.XArbitraryZVertical``, ``motion.referenceFrame.XArbitraryCorrectedZVertical``, ``motion.referenceFrame.XMagneticNorthZVertical``, ``motion.referenceFrame.XTrueNorthZVertical``.
 
-      The yaw of the device, in radians.
+   :param pitch: The pitch of the device, in radians.
+   :type pitch: number
 
-   .. lua:attribute:: roll: number
+   :param yaw: The yaw of the device, in radians.
+   :type yaw: number
 
-      The roll of the device, in radians.
+   :param roll: The roll of the device, in radians.
+   :type roll: number   
 
-   .. lua:attribute:: rotationMatrix: mat3x3
+   :param rotationMatrix: The rotation matrix that describes the device's orientation.
+   :type rotationMatrix: mat3x3
 
-      The rotation matrix that describes the device's orientation.
+   :param quaternion: The quaternion that describes the device's orientation.
+   :type quaternion: quat
 
-   .. lua:attribute:: quaternion: quat
+   :param referenceFrame: The reference frame in which motion metrics are tracked.
+   :type referenceFrame: integer      
 
-      The quaternion that describes the device's orientation.
+   .. lua:attribute:: XArbitraryZVertical: integer
 
-   .. lua:attribute:: referenceFrame: integer
+      The X-axis is arbitrary and the Z-axis is vertical.
 
-      The reference frame in which motion metrics are tracked.
+   .. lua:attribute:: XArbitraryCorrectedZVertical: integer
 
-      The value can be one of the following:
+      The X-axis is arbitrary and the Z-axis is vertical. The system will attempt to correct for the device's orientation.
+
+   .. lua:attribute:: XMagneticNorthZVertical: integer
+
+      The X-axis points toward the magnetic north and the Z-axis is vertical.
+
+   .. lua:attribute:: XTrueNorthZVertical: integer
+
+      The X-axis points toward the true north and the Z-axis is vertical.
 
-      - ``motion.referenceFrame.XArbitraryZVertical``: The X-axis is arbitrary and the Z-axis is vertical.
-      - ``motion.referenceFrame.XArbitraryCorrectedZVertical``: The X-axis is arbitrary and the Z-axis is vertical. The system will attempt to correct for the device's orientation.
-      - ``motion.referenceFrame.XMagneticNorthZVertical``: The X-axis points toward the magnetic north and the Z-axis is vertical.
-      - ``motion.referenceFrame.XTrueNorthZVertical``: The X-axis points toward the true north and the Z-axis is vertical.
+Magnetic Field Data
+===================
 
 .. lua:class:: magnetic
 

docs/source/api/style.rst

@@ -311,7 +311,7 @@ Constants - Blend Factors
    Blend factor of :math:`(f, f, f, 1)` where :math:`f = min(A_s, 1 - A_d)`
 
 Viewport
-#######
+########
 
 .. lua:function:: viewRect(x, y, w, h)