Home | Download/Install | Documentation | Packages | Screenshots | News | Forum/Mailing-lists | Contact | GForge
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. """
epydoc MODULES
where MODULES is the list of the modules to documentepydoc 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
$ epydoc –html -o core-0.4.0 ../src/core
$ tar -czvf core-0.40.tgz core-0.4.0