update doc

- add properties, parameters and commands to the doc string autoatically
- change names to "Frappy"
- started tutorial
- changed doc structure slightly

Change-Id: I87bef91384d138c738d12ddcf3a1de7f758a0973

secop/properties.py

@@ -30,13 +30,19 @@ from secop.errors import ProgrammingError, ConfigError, BadValueError
 
 # storage for 'properties of a property'
 class Property:
-    '''base class holding info about a property
+    """base class holding info about a property
 
-    properties are only sent to the ECS if export is True, or an extname is set
-    if mandatory is True, they MUST have a value in the cfg file assigned to them.
-    otherwise, this is optional in which case the default value is applied.
-    All values MUST pass the datatype.
-    '''
+    :param description: mandatory
+    :param datatype: the datatype to be accepted. not only to the SECoP datatypes are allowed!
+         also for example ``ValueType()`` (any type!), ``NoneOr(...)``, etc.
+    :param default: a default value. SECoP properties are normally not sent to the ECS,
+         when they match the default
+    :param extname: external name
+    :param export: sent to the ECS when True. defaults to True, when ``extname`` is given
+    :param mandatory: defaults to True, when ``default`` is not given. indicates that it must have a value
+       assigned from the cfg file (or, in case of a module property, it may be assigned as a class attribute)
+    :param settable: settable from the cfg file
+    """
     # note: this is intended to be used on base classes.
     #       the VALUES of the properties are on the instances!
     def __init__(self, description, datatype, default=None, extname='', export=False, mandatory=None, settable=True):
@@ -79,6 +85,17 @@ class Properties(OrderedDict):
         raise ProgrammingError('deleting Properties is not supported!')
 
 
+def add_extra_doc(cls, title, items):
+    """add bulleted list to doc string
+
+    using names and description of items
+    """
+    bulletlist = ['\n        - **%s** - %s' % (k, p.description) for k, p in items.items()]
+    if bulletlist:
+        doctext = '%s\n\n%s' % (title, ''.join(bulletlist))
+        cls.__doc__ = (cls.__doc__ or '') + '\n\n    %s\n' % doctext
+
+
 class PropertyMeta(type):
     """Metaclass for HasProperties
 
@@ -124,6 +141,8 @@ class PropertyMeta(type):
                     raise ProgrammingError('%r: property %r can not be set to %r'
                                             % (newtype, k, attrs[k]))
             setattr(newtype, k, property(getter))
+
+        add_extra_doc(newtype, '**properties**', attrs.get('properties', {}))  # only new properties
         return newtype