I'm thinking of using something called Sphinx to write our documentation for the software, because it's fast, easy, and generates easy-to-read, industry-standard documentation. I need to do some more research but from what I can tell it seems like a perfect match for our situation. It actually makes me feel excited about writing documentation (!)
Terry, here are some examples of the docstring syntax and the resulting documentation. Are you happy with this?
Syntax (taken from http://thomas-cokelaer.info/tutorials/s ... ython.html:
Code: Select all
"""This module illustrates how to write your docstring in OpenAlea
and other projects related to OpenAlea."""
__license__ = "Cecill-C"
__revision__ = " $Id: actor.py 1586 2009-01-30 15:56:25Z cokelaer $ "
__docformat__ = 'reStructuredText'
class MainClass1(object):
"""This class docstring shows how to use sphinx and rst syntax
The first line is brief explanation, which may be completed with
a longer one. For instance to discuss about its methods. The only
method here is :func:`function1`'s. The main idea is to document
the class and methods's arguments with
- **parameters**, **types**, **return** and **return types**::
:param arg1: description
:param arg2: description
:type arg1: type description
:type arg1: type description
:return: return description
:rtype: the return type description
- and to provide sections such as **Example** using the double commas syntax::
:Example:
followed by a blank line !
which appears as follow:
:Example:
followed by a blank line
- Finally special sections such as **See Also**, **Warnings**, **Notes**
use the sphinx syntax (*paragraph directives*)::
.. seealso:: blabla
.. warnings also:: blabla
.. note:: blabla
.. todo:: blabla
.. note::
There are many other Info fields but they may be redundant:
* param, parameter, arg, argument, key, keyword: Description of a
parameter.
* type: Type of a parameter.
* raises, raise, except, exception: That (and when) a specific
exception is raised.
* var, ivar, cvar: Description of a variable.
* returns, return: Description of the return value.
* rtype: Return type.
.. note::
There are many other directives such as versionadded, versionchanged,
rubric, centered, ... See the sphinx documentation for more details.
Here below is the results of the :func:`function1` docstring.
"""
def function1(self, arg1, arg2, arg3):
"""returns (arg1 / arg2) + arg3
This is a longer explanation, which may include math with latex syntax
:math:`\\alpha`.
Then, you need to provide optional subsection in this order (just to be
consistent and have a uniform documentation. Nothing prevent you to
switch the order):
- parameters using ``:param <name>: <description>``
- type of the parameters ``:type <name>: <description>``
- returns using ``:returns: <description>``
- examples (doctest)
- seealso using ``.. seealso:: text``
- notes using ``.. note:: text``
- warning using ``.. warning:: text``
- todo ``.. todo:: text``
**Advantages**:
- Uses sphinx markups, which will certainly be improved in future
version
- Nice HTML output with the See Also, Note, Warnings directives
**Drawbacks**:
- Just looking at the docstring, the parameter, type and return
sections do not appear nicely
:param arg1: the first value
:param arg2: the first value
:param arg3: the first value
:type arg1: int, float,...
:type arg2: int, float,...
:type arg3: int, float,...
:returns: arg1/arg2 +arg3
:rtype: int, float
:Example:
>>> import template
>>> a = template.MainClass1()
>>> a.function1(1,1,1)
2
.. note:: can be useful to emphasize
important feature
.. seealso:: :class:`MainClass2`
.. warning:: arg2 must be non-zero.
.. todo:: check that arg2 is non zero.
"""
return arg1/arg2 + arg3
if __name__ == "__main__":
import doctest
doctest.testmod()
You can (and we should) theme the output to make it look pretty and easy to read, so it can look like any of these: http://www.sphinx-doc.org/en/stable/theming.html, 'Builtin Themes' section.
Is it alright with all of you if I go ahead with this?
Hamish
