enhance documentation

- flatten hierarchy (some links do not work when using folders)
+ fix a bug with the redorder flag in Override
+ allow removal of parameters
+ clean description using inspect.cleandoc

Change-Id: I3dde4f4cb29c46e8a21014f1fad7aa3ad610a1bf

secop/properties.py

@@ -24,8 +24,10 @@
 
 
 from collections import OrderedDict
+from inspect import cleandoc
 
 from secop.errors import ProgrammingError, ConfigError, BadValueError
+from secop.lib.classdoc import append_to_doc, indent_description
 
 
 # storage for 'properties of a property'
@@ -33,7 +35,7 @@ class Property:
     """base class holding info about a property
 
     :param description: mandatory
-    :param datatype: the datatype to be accepted. not only to the SECoP datatypes are allowed!
+    :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
@@ -48,7 +50,7 @@ class Property:
     def __init__(self, description, datatype, default=None, extname='', export=False, mandatory=None, settable=True):
         if not callable(datatype):
             raise ValueError('datatype MUST be a valid DataType or a basic_validator')
-        self.description = description
+        self.description = cleandoc(description)
         self.default = datatype.default if default is None else datatype(default)
         self.datatype = datatype
         self.extname = extname
@@ -85,17 +87,6 @@ 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
 
@@ -142,7 +133,21 @@ class PropertyMeta(type):
                                             % (newtype, k, attrs[k]))
             setattr(newtype, k, property(getter))
 
-        add_extra_doc(newtype, '**properties**', attrs.get('properties', {}))  # only new properties
+        # add property information to the doc string
+        def fmt_property(name, prop):
+            desc = indent_description(prop)
+            if '(' in desc[0:2]:
+                dtinfo = ''
+            else:
+                dtinfo = [prop.datatype.short_doc(), None if prop.export else 'hidden']
+                dtinfo = ', '.join(filter(None, dtinfo))
+                if dtinfo:
+                    dtinfo = '*(%s)* ' % dtinfo
+            return '- **%s** - %s%s\n' % (name, dtinfo, desc)
+
+        append_to_doc(newtype, 'properties', 'SECOP Properties',
+                      'properties', attrs.get("properties", {}), fmt_property)
+
         return newtype