OpenAlea packages can be used at the python level. That means package functionality must be accessible via a Python interpreter. Without documentation, these functionalities are useless. That's why OpenAlea charter precise that each package must be distributed with a complete documentation, and particularly the Python API.

Python documentation strings (or docstrings) provide a convenient way of associating documentation with Python modules, functions, classes, and methods. An object's docstring is defined by including a string constant as the first statement in the object's definition. For example, the following function defines a docstring:

def x_intercept(m, b):
    """
    Return the x intercept of the line y=m*x+b.  The x intercept of a
    line is the point at which it crosses the x axis (y=0).
    """
    return -b/m

Docstrings can be accessed from the interpreter and from Python programs using the “help” command:

>>> help(x_intercept)
Help on function x_intercept in module __main__:
 
x_intercept(m, b)
    Return the x intercept of the line y=m*x+b.  The x intercept of a
    line is the point at which it crosses the x axis (y=0).

For more information about Python docstrings, see the Python Tutorial.

from epydoc documentation

Docstrings are useful in the Python interpreter but are insufficient to create an complete document.

Epydoc is a tool for generating API documentation for Python modules, based on their docstrings. For an example of epydoc's output, see the API documentation for epydoc itself (html, pdf). A lightweight markup language called epytext can be used to format docstrings, and to add information about specific fields, such as parameters and instance variables.

Epydoc also understands docstrings written in ReStructuredText.

Read the Epydoc documentation.

Restructuredtext example:

"""
Module description
"""
 
__docformat__ = "restructuredtext en"
 
def fox_speed(size, weight, age):
    """
    Return the maximum speed for a fox.
 
    :Parameters:
      - `size`: The size of the fox (in meters)
      - `weight`: The weight of the fox (in stones)
      - `age`: The age of the fox (in years)
 
    """

Here is a more detailed description of what should be done so as to make the sphinx documentation optimal, while keeping the docstring readable.

def example(arg1):
    """Brief synopsis on 1 line, COMPULSORY
 
    This is a longer explanation, which 
    may include math :math:`\\alpha`, which is OPTIONAL
 
    Followed by compulsory sections: 
      - "Parameters"
      - "Returns"
      - "Examples"
 
    The "Returns Type" section being optional
 
    The "Examples" uses the doctest syntax. They must be self consistent as much as possible, 
    and they can be copy and paste into a ipython session.
 
    Note the syntax for the "parameters": 
    [2 spaces, a dash, a space, a backquote, argument name, backquote, space, (type), space, dash, space, description]
 
    Then, add optional section using sphinx directives ".. todo::, ".. warnings::" etc. 
 
    Note again the space between ".." and    the keyword.
 
    Add 1 blank line betweem sections
 
    Add indentation when starting the content of a section.
 
    :Parameters:
      - `arg1` (int,float,...) - the first value
      - `arg2` (int,float,...) - the first value
      - `arg3` (int,float,...) - the first value
 
    :Returns:
        arg1/arg2 +arg3
 
    :Returns Type:
        int,float 
 
    :Examples:        
 
    >>> import template
    >>> a = MainClass()
    >>> a.function2(1,1,1)
    2
 
    .. note:: can be useful to emphasize 
        important feature (NOTE THE INDENTATION)
    .. seealso:: :class:`MainClass2`
    .. warning:: arg2 must be non-zero.
    .. todo:: check that arg2 is non zero.
"""

• Install the module you want to document
• run the command epydoc MODULES where MODULES is the list of the modules to document

epydoc openalea.starter.scenecontainer openalea.starter.sceneobject

Use the folowing convention to specify the expected type of a parameter:

Simple Types

int, float, None, str, bool, cplx, slice

Any Types

Any

Classes

class
subclass of classname

Complex Types

class
module.class

Containers

tuple [ of value ]
list [ of value ]
dict [ of key:value ]
iter [ of value ]
'(v1, v2, v3, ...)' ou 'v1, v2, v3, ...' for return values
other [ of value ] ===== Epydoc / ReStructuredText ====

Functions

funct(arg1, arg2, ...) -> return

Examples

list of (int|float) = list of integer or float
list of (int,int) = list of tuple (int,int)
list of int | float = list of integer or float
iter of funct(int,int)->float

• Generate the doc :
  • $ epydoc –html -o core-0.4.0 ../src/core
• Create an Archive zip or tgz containing all the generated files:
  • $ tar -czvf core-0.40.tgz core-0.4.0
• Upload the files with the following form (need authentification).