autogenerate docstrings for Process subclasses (process interface)

[benbovy]

Each Process subclass defines an interface which consists of a set of Variable objects (or similar) defined as class attributes.

For more introspection and for documentation purpose (e.g., sphinx autodoc), it would be nice to describe a process interface in the class docstring as an Attributes section, following the numpy doc style.

This can be done automatically using the ProcessBase metaclass. This would avoid writing the same things twice, as information like description or allowed dimensions is already defined in the Variableobjects.

For example

>>> class StackedGrid(Process):
...    """A 2-d stacked grid."""
...    x = Variable('node', description='x coordinate labels')
...    y = Variable('node', description='y coordinate labels')

It would give

>>> print(StackedGrid.__doc__)
StackedGrid
    
    A 2-d stacked grid.

    Attributes
    ----------
    x : Variable
        x coordinate labels.
    y : Variable
        y coordinate labels.

The auto-generate function might also be smart enough so that it provides meaningful documentation text from variable attributes, e.g.,

• allowed_dims=() -> scalar
• allowed_dims=('node') -> 1-d array with dimension 'node'
• default value is 2
• ...

An issue with this feature is that it would not strictly following the numpy guidelines:

An Attributes section, located below the Parameters section, may be used to describe non-method attributes of the class

It is not really the case here. There is some magic happening when a Process subclass is created (using the metaclass): the defined Variable objects are actually not accessible as class attributes, although when a Process subclass is instantiated it supports back attribute-like access for these objects.

[benbovy]

Alternatively, using a decorator would be more explicit, e.g.,

@autodoc_vars
class StackedGrid(Process):
    """A 2-d stacked grid.

    {{attributes_section}}
    """
    x = Variable('node', description='x coordinate labels')
    y = Variable('node', description='y coordinate labels')

[benbovy]

Reusing the process decorator is the best option.

@xs.process(autodoc=True)
class StackedGrid:
    """A 2-d stacked grid.

    {{attributes_section}}
    """
    x = xs.variable('node', description='x coordinate labels')
    y = xs.variable('node', description='y coordinate labels')

[benbovy]

Closed in #67