[cgkit-commits] SF.net SVN: cgkit:[334] cgkit/trunk/cgkit

[<mb...@us...>]

Revision: 334
          http://cgkit.svn.sourceforge.net/cgkit/?rev=334&view=rev
Author:   mbaas
Date:     2009-08-15 09:31:07 +0000 (Sat, 15 Aug 2009)

Log Message:
-----------
Changed doc strings to use rst markup so that they can be used for the Sphinx documentation.

Modified Paths:
--------------
    cgkit/trunk/cgkit/glslangparams.py
    cgkit/trunk/cgkit/glslangtokenize.py
    cgkit/trunk/cgkit/pointcloud.py
    cgkit/trunk/cgkit/ri.py
    cgkit/trunk/cgkit/sloargs.py
    cgkit/trunk/cgkit/slparams.py
    cgkit/trunk/cgkit/sltokenize.py

Modified: cgkit/trunk/cgkit/glslangparams.py
===================================================================
--- cgkit/trunk/cgkit/glslangparams.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/glslangparams.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -327,38 +327,38 @@
 def glslangparams(shader=None, cpp=None, cpperrstream=sys.stderr):
     """Extracts the shader parameters from an OpenGL 2 shader source file.
 
-    The argument shader is either the name of the shader source file
+    The argument *shader* is either the name of the shader source file
     or a file-like object that provides the shader sources.
-    cpp determines how the shader source is preprocessed. It
+    *cpp* determines how the shader source is preprocessed. It
     can either be a string containing the name of an external
-    preprocessor tool (such as 'cpp') that must take the file name as
+    preprocessor tool (such as ``cpp``) that must take the file name as
     parameter and dump the preprocessed output to stdout or it can be
-    a callable that takes shader and cpperrstream as input and returns
+    a callable that takes *shader* and *cpperrstream* as input and returns
     the preprocessed sources as a string. If the external
-    preprocessor does not produce any data a PreprocessorNotFound
+    preprocessor does not produce any data a :exc:`PreprocessorNotFound`
     exception is thrown.
     The error stream of the preprocessor is written to the object
-    that is specified by cpperrstream which must have a write()
-    method. If cpperrstream is None, the error stream is ignored.
+    that is specified by *cpperrstream* which must have a :meth:`write()`
+    method. If *cpperrstream* is ``None``, the error stream is ignored.
 
-    If cpp is None a simple internal preprocessor based on the
-    simplecpp module is used.
+    If *cpp* is ``None`` a simple internal preprocessor based on the
+    :mod:`simplecpp` module is used.
 
-    The function returns three lists (uniform, attribute, varying)
+    The function returns three lists (*uniform*, *attribute*, *varying*)
     that contain the variables with the corresponding qualifier.
 
-    A uniform variable is a 5-tuple (type, identifier, arraysize,
-    structname, struct). arraysize is a string containing the
+    A uniform variable is a 5-tuple (*type*, *identifier*, *arraysize*,
+    *structname*, *struct*). *arraysize* is a string containing the
     expression for the length of the array (i.e. the value between
-    the square brackets). If the variable is no array, arraysize is None.
-    When the variable is a struct, type has the value 'struct'. In this
-    case, the struct is given in struct (which is itself a list of
+    the square brackets). If the variable is no array, *arraysize* is ``None``.
+    When the variable is a struct, *type* has the value ``'struct'``. In this
+    case, the struct is given in *struct* (which is itself a list of
     variables as 5-tuples). If the struct has a name, this name is
-    given in structname, otherwise structname is None.
+    given in *structname*, otherwise *structname* is ``None``.
 
-    An attribute variable is a 2-tuple (type, identifier) and a
-    varying variable is a 3-tuple (type, identifier, arraysize) where
-    arraysize is defined as in the uniform case.
+    An attribute variable is a 2-tuple (*type*, *identifier*) and a
+    varying variable is a 3-tuple (*type*, *identifier*, *arraysize*) where
+    *arraysize* is defined as in the uniform case.
     """
 
     # Run the preprocessor on the input file...

Modified: cgkit/trunk/cgkit/glslangtokenize.py
===================================================================
--- cgkit/trunk/cgkit/glslangtokenize.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/glslangtokenize.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -52,21 +52,35 @@
 def tokenize(readline, tokeater):
     """Reads a Shading Language input stream and creates tokens.
 
-    The first parameter, readline, must be a callable object which
-    provides the same interface as the readline() method of built-in
+    The first parameter, *readline*, must be a callable object which
+    provides the same interface as the :meth:`readline()` method of built-in
     file objects. Each call to the function should return one line of
     input as a string.
 
-    The second parameter, tokeneater, must also be a callable object.
+    The second parameter, *tokeater*, must also be a callable object.
     It is called with six parameters: the token type, the token
-    string, a tuple (srow, scol) specifying the row and column where
-    the token begins in the source, a tuple (erow, ecol) giving the
+    string, a tuple (*srow*, *scol*) specifying the row and column where
+    the token begins in the source, a tuple (*erow*, *ecol*) giving the
     ending position of the token, the line on which the token was
     found and the filename of the current file.
 
-    By default the filename argument is an empty string. It will only
+    The token type can be one of
+
+    * ``WHITESPACE``: This is a series of blanks and/or tabs.
+    * ``NAME``: A valid identifier name or keyword.
+    * ``NUMBER``: An integer or float.
+    * ``STRING``: A string enclosed in ``'"'``.
+    * ``NEWLINE``: A newline character.
+    * ``OPERATOR``: An operator such as ``'+', '-', '!', '==', '!='``, etc.
+    * ``CHARACTER``: A single character that doesn't fit anything else.
+    * ``TYPE``: A language type (``void``, ``bool``, ``float``, ``int``, ``vec2``,
+      ``vec3``, ``vec4``, etc.)
+    * ``QUALIFIER``: A type qualifier (``const``, ``attribute``, ``uniform``,
+      ``varying``, ``in``, ``out``, ``inout``)
+
+    By default, the filename argument is an empty string. It will only
     be the actual filename if you provide a preprocessed file stream
-    as input (so you should first run cpp on any shader). The
+    as input (so you should first run ``cpp`` on any shader). The
     tokenizer actually expects preprocessed data as it doesn't handle
     comments.
     """

Modified: cgkit/trunk/cgkit/pointcloud.py
===================================================================
--- cgkit/trunk/cgkit/pointcloud.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/pointcloud.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -606,16 +606,19 @@
 def open(fileName, mode="r", libName=None, **kwargs):
     """Open a point cloud file for reading or writing.
     
-    fileName is the name of the point cloud file. mode is either "r"
-    for reading a file or "w" for writing a new point cloud file.
-    libName is the library name that implements the point cloud API.
-    When mode is "w", the following additional keyword arguments must
+    *fileName* is the name of the point cloud file. *mode* is either ``"r"``
+    for reading a file or ``"w"`` for writing a new point cloud file.
+    *libName* is the library name that implements the point cloud API.
+    When mode is ``"w"``, the following additional keyword arguments must
     be present:
     
-    - vars: A list of tuples (type, name) that defines what additional variables to write
-    - world2eye: The world2eye matrix 
-    - world2ndc: The world2ndc matrix
-    - format: A tuple (xres, yres, aspect) 
+    - ``vars``: A list of tuples (*type*, *name*) that defines what additional variables to write
+    - ``world2eye``: The world2eye matrix 
+    - ``world2ndc``: The world2ndc matrix
+    - ``format``: A tuple (*xres*, *yres*, *aspect*)
+    
+    Depending on the mode, the function either returns a :class:`PtcReader` or
+    :class:`PtcWriter` object.
     """
     if mode=="r":
         return PtcReader(fileName, libName, **kwargs)

Modified: cgkit/trunk/cgkit/ri.py
===================================================================
--- cgkit/trunk/cgkit/ri.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/ri.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -48,7 +48,7 @@
 Interface specification. However, it also supports some newer features
 such as string handles for light sources or object instances.
 
-It is safe to import the module using 
+It is safe to import the module using::
 
   from cgkit.ri import *
 
@@ -57,7 +57,7 @@
 naming conflict.
 
 After importing the module this way you can use the functions just as
-you are used to from the C API (well, almost).
+you are used to from the C API::
 
   from cgkit.ri import *
 

Modified: cgkit/trunk/cgkit/sloargs.py
===================================================================
--- cgkit/trunk/cgkit/sloargs.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/sloargs.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -518,10 +518,10 @@
 _sloLibNames = {}
 
 def registerSloArgs(sloSuffix, sloArgsCls):
-    """Register a SloArgs class for a particular renderer.
+    """Register a :class:`SloArgs` class for a particular renderer.
     
-    sloSuffix is the suffix (without dot) that is used for the compiled
-    shaders of this renderer. sloArgsCls is the SloArgs class that
+    *sloSuffix* is the suffix (without dot) that is used for the compiled
+    shaders of this renderer. *sloArgsCls* is the :class:`SloArgs` class that
     can read compiled shaders for this renderer.
     """
     global _sloArgsClasses
@@ -532,9 +532,15 @@
 def getSloLib(sloSuffix):
     """Return the library name that manages a particular type of compiled shaders.
     
-    sloSuffix is the suffix of the compiled shaders.
+    *sloSuffix* is the suffix of the compiled shader.
     The return value is the library name that is used to read the parameters
     from compiled shaders of the given suffix.
+    
+    When called before a shader was parsed, the return value is the
+    library name that will be used when the library is loaded. This value can be
+    set by calling :func:`setSloLib()`. When the function is called after a
+    shader was already parsed, the return value is the absolute path to the
+    actual library that is used to read parameters.
     """
     global _sloArgsClasses, _sloArgsInstances
     
@@ -549,10 +555,10 @@
 def setSloLib(sloSuffix, libName):
     """Set the library name that should be used for reading shader parameters.
     
-    Shaders with the given suffix (case-insensitive) will be handled by
-    the given library. This function has no effect if a shader of the given
+    Shaders with the suffix *sloSuffix* (case-insensitive) will be handled by
+    the library *libName*. This function has no effect if a shader of the given
     suffix has already been read. You must call this function at the beginning
-    of your application when slparams() hasn't been called yet.
+    of your application when :func:`slparams()` hasn't been called yet.
     """
     global _sloLibNames
     
@@ -561,7 +567,7 @@
 def slparams(shader):
     """Read shader parameters.
     
-    See slparams.slparams() for more details.
+    See :func:`slparams.slparams()<cgkit.slparams.slparams>` for more details.
     """
     global _sloArgsClasses, _sloArgsInstances, _sloLibNames
     

Modified: cgkit/trunk/cgkit/slparams.py
===================================================================
--- cgkit/trunk/cgkit/slparams.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/slparams.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -228,59 +228,89 @@
 def slparams(slfile=None, cpp=None, cpperrstream=sys.stderr, slname=None, includedirs=None, defines=None):
     """Extracts the shader parameters from a RenderMan Shader file.
 
-    The argument slfile is either the name of a compiled shader, the name of
-    the shader source file (*.sl) or a file-like object that provides the
-    shader sources.  cpp determines how the shader source is preprocessed.
+    The argument *slfile* is either the name of a compiled shader, the name of
+    the shader source file (``*.sl``) or a file-like object that provides the
+    shader sources.
+    
+    *cpp* determines how the shader source is preprocessed.
     It can either be a string containing the name of an external
-    preprocessor tool (such as 'cpp') that must take the file name as
+    preprocessor tool (such as ``cpp``) that must take the file name as
     parameter and dump the preprocessed output to stdout or it can be
-    a callable that takes slfile and cpperrstream as input and returns
+    a callable that takes *slfile* and *cpperrstream* as input and returns
     the preprocessed sources as a string. If the external
-    preprocessor does not produce any data a PreprocessorNotFound
+    preprocessor does not produce any data a :exc:`PreprocessorNotFound`
     exception is thrown.
     The error stream of the preprocessor is written to the object
-    that's specified by cpperrstream which must have a write()
-    method. If cpperrstream is None, the error stream is ignored.
+    specified by *cpperrstream* which must have a :meth:`write()`
+    method. If *cpperrstream* is ``None``, the error stream is ignored.
 
-    If cpp is None a simple internal preprocessor based on the
-    simplecpp module is used.
-    The slname argument is an alias for slfile, it's only available
+    If *cpp* is ``None`` a simple internal preprocessor based on the
+    :mod:`simplecpp` module is used.
+    The *slname* argument is an alias for *slfile*, it is only available
     for backwards compatibility.
     
-    includedirs is a list of strings that contain directories where to
-    look for include files. defines is a list of tuples (name, value)
+    *includedirs* is a list of strings that contain directories where to
+    look for include files. *defines* is a list of tuples (*name*, *value*)
     that specify the predefined symbols to use.
     
     The function returns a list of shader info objects. These objects have
-    4 attributes:
+    four attributes:
     
-    - type: The type of the shader (surface, displacement, etc.)
-    - name: The name of the shader
-    - params: The shader parameters (see below)
-    - meta: The shader meta data. How exactly meta data is specified depends
-            on the renderer you are using.
+    - ``type``: The type of the shader (surface, displacement, etc.)
+    - ``name``: The name of the shader
+    - ``params``: The shader parameters (see below)
+    - ``meta``: The shader meta data. How exactly meta data is specified depends
+      on the renderer you are using.
      
     The parameters are given as a list of shader parameter objects
     describing each parameter. A shader parameter object has the
     following attributes:
 
-    - outputSpec: The output specifier (either "output" or an empty string)
-    - storage: The storage class ("uniform" or "varying")
-    - type: The parameter type
-    - size: The array length or None if the parameter is not an array
-    - name: The name of the parameter
-    - space: The space in which a point-like type was defined
-    - default: The "raw" default value. If the input was a shader source file,
+    - ``outputSpec``: The output specifier (either ``"output"`` or an empty string)
+    - ``storage``: The storage class (``"uniform"`` or ``"varying"``)
+    - ``type``: The parameter type
+    - ``size``: The array length or ``None`` if the parameter is not an array
+    - ``name``: The name of the parameter
+    - ``space``: The space in which a point-like type was defined
+    - ``default``: The "raw" default value. If the input was a shader source file,
       this will always be a string containing an expression. If the input was
       a compiled shader this will already be an appropriate Python value.
-      You should never use this value directly, but always use convertdefault()
+      You should never use this value directly, but always use :func:`convertdefault()`
       to obtain a value which can be further processed. This way, your code
       will work for both, compiled shaders and shader source files.
     
     For backwards compatibility, the shader info object behaves like a
-    3-tuple (type, name, params). The meta data can only be accessed via name
-    though. The shader parameter objects can also be used like 7-tuples
+    3-tuple (*type*, *name*, *params*). The meta data can only be accessed via
+    name though. The shader parameter objects can also be used like 7-tuples
     containing the above data (in the order given above).
+    
+    Example (output slightly reformatted for better readability)::
+
+      >>> from cgkit import slparams
+      >>> shaders = lparams.slparams("plastic.sl")
+      >>> print shaders
+      [('surface', 'plastic', 
+        [('', 'uniform', 'float', None, 'Ka', None, '1'),
+         ('', 'uniform', 'float', None, 'Kd', None, '0.5'),
+         ('', 'uniform', 'float', None, 'Ks', None, '0.5'),
+         ('', 'uniform', 'float', None, 'roughness', None, '0.1'),
+         ('', 'uniform', 'color', None, 'specularcolor', 'rgb', '1')])]
+      >>> shaders[0].type
+      'surface'
+      >>> shaders[0].name
+      'plastic'
+      >>> for param in shaders[0].params: print param.name
+      ... 
+      Ka
+      Kd
+      Ks
+      roughness
+      specularcolor
+      >>> shaders[0].meta
+      {}
+
+    The parser used inside this function was generated using the parser generator
+    `Yapps <http://theory.stanford.edu/~amitp/Yapps/>`_  by Amit Patel.
     """
 
     if slname is not None:
@@ -433,22 +463,33 @@
 def convertdefault(paramtuple):
     """Converts the default value of a shader parameter into a Python type.
 
-    paramtuple must be a 7-tuple (or parameter object) as returned by slparams().
+    *paramtuple* must be a 7-tuple (or parameter object) as returned by 
+    :func:`slparams()`.
     The function returns a Python object that corresponds to the default
     value of the parameter. If the default value can't be converted
-    then None is returned. Only the functions that are present in the
-    sl module are evaluated. If a default value calls a user defined
-    function then None is returned.
+    then ``None`` is returned. Only the functions that are present in the
+    :mod:`sl<cgkit.sl>` module are evaluated. If a default value calls a user defined
+    function then ``None`` is returned.
 
     The SL types will be converted into the following Python types:
 
-    - float  -> float
-    - string -> string
-    - color  -> vec3
-    - point  -> vec3
-    - vector -> vec3
-    - normal -> vec3
-    - matrix -> mat4
+        +------------+-------------+
+        | SL type    | Python type |
+        +============+=============+
+        | ``float``  | ``float``   |
+        +------------+-------------+
+        | ``string`` | ``string``  |
+        +------------+-------------+
+        | ``color``  | ``vec3``    |
+        +------------+-------------+
+        | ``point``  | ``vec3``    |
+        +------------+-------------+
+        | ``vector`` | ``vec3``    |
+        +------------+-------------+
+        | ``normal`` | ``vec3``    |
+        +------------+-------------+
+        | ``matrix`` | ``mat4``    |
+        +------------+-------------+
 
     Arrays will be converted into lists of the corresponding type.
     """

Modified: cgkit/trunk/cgkit/sltokenize.py
===================================================================
--- cgkit/trunk/cgkit/sltokenize.py	2009-08-08 12:58:38 UTC (rev 333)
+++ cgkit/trunk/cgkit/sltokenize.py	2009-08-15 09:31:07 UTC (rev 334)
@@ -51,21 +51,32 @@
 def tokenize(readline, tokeater):
     """Reads a Shading Language input stream and creates tokens.
 
-    The first parameter, readline, must be a callable object which
-    provides the same interface as the readline() method of built-in
+    The first parameter, *readline*, must be a callable object which
+    provides the same interface as the :meth:`readline()` method of built-in
     file objects. Each call to the function should return one line of
     input as a string.
 
-    The second parameter, tokeneater, must also be a callable object.
+    The second parameter, *tokeater*, must also be a callable object.
     It is called with six parameters: the token type, the token
-    string, a tuple (srow, scol) specifying the row and column where
-    the token begins in the source, a tuple (erow, ecol) giving the
+    string, a tuple (*srow*, *scol*) specifying the row and column where
+    the token begins in the source, a tuple (*erow*, *ecol*) giving the
     ending position of the token, the line on which the token was
     found and the filename of the current file.
 
-    By default the filename argument is an empty string. It will only
+    The token type can be one of:
+    
+    * ``WHITESPACE``: This is a series of blanks and/or tabs
+    * ``NAME``: A valid identifier name or keyword
+    * ``NUMBER``: An integer or float
+    * ``STRING``: A string enclosed in ``'"'``.
+    * ``NEWLINE``: A newline character.
+    * ``OPERATOR``: An operator such as ``'+', '-', '!', '==', '!='``, etc.
+    * ``CHARACTER``: A single character that doesn't fit anything else.
+    * ``TYPE``: A Shading Language type (float, point, vector, normal, matrix, color)
+
+    By default, the filename argument is an empty string. It will only
     be the actual filename if you provide a preprocessed file stream
-    as input (so you should first run cpp on any shader). The
+    as input (so you should first run ``cpp`` on any shader). The
     tokenizer actually expects preprocessed data as it doesn't handle
     comments.
     """


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.