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
2021-01-25 15:12:47 +01:00
parent e411ded55b
commit bc5edec06f
32 changed files with 608 additions and 381 deletions
--- a/secop/lib/classdoc.py
+++ b/secop/lib/classdoc.py
@@ -0,0 +1,76 @@
+#  -*- coding: utf-8 -*-
+# *****************************************************************************
+#
+# This program is free software; you can redistribute it and/or modify it under
+# the terms of the GNU General Public License as published by the Free Software
+# Foundation; either version 2 of the License, or (at your option) any later
+# version.
+#
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License along with
+# this program; if not, write to the Free Software Foundation, Inc.,
+# 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
+# Module authors:
+#   Markus Zolliker <markus.zolliker@psi.ch>
+#
+# *****************************************************************************
+
+from inspect import cleandoc
+from textwrap import indent
+
+
+def indent_description(p):
+    """indent lines except first one"""
+    return indent(p.description, '    ').replace('    ', '', 1)
+
+
+def append_to_doc(cls, name, title, attrname, newitems, fmtfunc):
+    """add information about some items to the doc
+
+    :param cls: the class with the doc string to be extended
+    :param name: the name of the attribute dict to be used
+    :param title: the title to be used
+    :param newitems: the set of new items defined for this class
+    :param fmtfunc: a function returning a formatted item to be displayed, including line feed at end
+       or an empty string to suppress output for this item
+    :type fmtfunc: function(key, value)
+    """
+    doc = cleandoc(cls.__doc__ or '')
+    allitems = getattr(cls, attrname, {})
+    fmtdict = {n: fmtfunc(n, p) or '  - **%s** *removed*\n' % n for n, p in allitems.items()}
+    head, _, tail = doc.partition('{all %s}' % name)
+    if tail:  # take all
+        inherited = set()
+        fmted = ''.join(fmtdict.values())
+    else:
+        inherited = {n: p for n, p in allitems.items() if fmtdict.get(n) and n not in newitems}
+        fmted = ''.join('  ' + v for k, v in fmtdict.items() if k in newitems)
+        head, _, tail = doc.partition('{%s}' % name)
+        if not tail:
+            head, _, tail = doc.partition('{no %s}' % name)
+            if tail:  # add no information
+                return
+            # no tag found: append to the end
+    if fmted:
+        clsset = set()
+        for name in inherited:
+            p = allitems[name]
+            refcls = cls
+            for base in cls.__mro__:
+                dp = getattr(base, attrname, {}).get(name)
+                if dp:
+                    if dp == p:
+                        refcls = base
+                    else:
+                        break
+            clsset.add(refcls)
+        clsset.discard(cls)
+        if clsset:
+            fmted += '  - see also %s\n' % (', '.join(':class:`%s.%s`' % (c.__module__, c.__name__)
+                                                      for c in cls.__mro__ if c in clsset))
+        cls.__doc__ = '%s\n\n:%s: %s\n%s' % (head, title, fmted, tail)