ENH: Concat class and __init__ docstrings; have Class.params()

Fixes #24

Author: kernc

pdoc/__init__.py

@@ -401,6 +401,7 @@ class Context(dict):
     If you don't pass your own `Context` instance to `Module` constructor,
     a global context object will be used.
     """
+    __pdoc__['Context.__init__'] = False
 
 
 _global_context = Context()
@@ -981,7 +982,8 @@ def _link_inheritance(self):
                          'use `__pdoc__[key] = False` '
                          '(key: {!r}, module: {!r}).'.format(name, self.name))
 
-                if name not in self.doc and refname not in self._context:
+                if (not name.endswith('.__init__') and
+                        name not in self.doc and refname not in self._context):
                     warn('__pdoc__-overriden key {!r} does not exist '
                          'in module {!r}'.format(name, self.name))
 
@@ -1073,6 +1075,10 @@ def find_ident(self, name: str) -> Doc:
         `External` is returned populated with the given identifier.
         """
         _name = name.rstrip('()')  # Function specified with parentheses
+
+        if _name.endswith('.__init__'):  # Ref to class' init is ref to class itself
+            _name = _name[:-len('.__init__')]
+
         return (self.doc.get(_name) or
                 self._context.get(_name) or
                 self._context.get(self.name + '.' + _name) or
@@ -1127,6 +1133,11 @@ class Class(Doc):
 
     def __init__(self, name, module, obj, *, docstring=None):
         assert isinstance(obj, type)
+        if docstring is None:
+            init_doc = inspect.getdoc(obj.__init__) or ''
+            if init_doc == object.__init__.__doc__:
+                init_doc = ''
+            docstring = ((inspect.getdoc(obj) or '') + '\n\n' + init_doc).strip()
         super().__init__(name, module, obj, docstring=docstring)
 
         self.doc = {}
@@ -1138,8 +1149,7 @@ def __init__(self, name, module, obj, *, docstring=None):
                        for name, obj in inspect.getmembers(self.obj)
                        # Filter only *own* members. The rest are inherited
                        # in Class._fill_inheritance()
-                       if (name in self.obj.__dict__ and
-                           (_is_public(name) or name == '__init__'))]
+                       if name in self.obj.__dict__ and _is_public(name)]
         index = list(self.obj.__dict__).index
         public_objs.sort(key=lambda i: index(i[0]))
 
@@ -1214,6 +1224,22 @@ def subclasses(self) -> List['Class']:
         return [self.module.find_class(c)
                 for c in type.__subclasses__(self.obj)]
 
+    def params(self, *, annotate=False) -> List['str']:
+        """
+        Return a list of formatted parameters accepted by the
+        class constructor (method `__init__`). See `pdoc.Function.params`.
+        """
+        name = self.name + '.__init__'
+        qualname = self.qualname + '.__init__'
+        refname = self.refname + '.__init__'
+        exclusions = getattr(self.module.obj, "__pdoc__", {})
+        if name in exclusions or qualname in exclusions or refname in exclusions:
+            return []
+
+        params = Function._params(self.obj.__init__, annotate=annotate)
+        params = params[1:] if params[0] == 'self' else params
+        return params
+
     def _filter_doc_objs(self, type: Type[T], include_inherited=True,
                          filter_func: Callable[[T], bool] = lambda x: True,
                          sort=True) -> List[T]:
@@ -1319,7 +1345,7 @@ class Function(Doc):
 
     def __init__(self, name, module, obj, *, cls: Class = None, method=False):
         """
-        Same as `pdoc.Doc.__init__`, except `obj` must be a
+        Same as `pdoc.Doc`, except `obj` must be a
         Python function object. The docstring is gathered automatically.
 
         `cls` should be set when this is a method or a static function
@@ -1392,8 +1418,12 @@ def params(self, *, annotate: bool = False) -> List[str]:
 
         [PEP 484]: https://www.python.org/dev/peps/pep-0484/
         """
+        return self._params(self.obj, annotate=annotate)
+
+    @staticmethod
+    def _params(func_obj, annotate=False):
         try:
-            signature = inspect.signature(inspect.unwrap(self.obj))
+            signature = inspect.signature(inspect.unwrap(func_obj))
         except ValueError:
             # I guess this is for C builtin functions?
             return ["..."]
@@ -1436,10 +1466,6 @@ def __repr__(self):
 
         return params
 
-    def __lt__(self, other):
-        # Push __init__ to the top.
-        return self.name == '__init__' or super().__lt__(other)
-
     @property
     def refname(self):
         return (self.cls.refname if self.cls else self.module.refname) + '.' + self.name
@@ -1455,7 +1481,7 @@ class Variable(Doc):
     def __init__(self, name, module, docstring, *,
                  obj=None, cls: Class = None, instance_var=False):
         """
-        Same as `pdoc.Doc.__init__`, except `cls` should be provided
+        Same as `pdoc.Doc`, except `cls` should be provided
         as a `pdoc.Class` object when this is a class or instance
         variable.
         """

pdoc/templates/css.mako

@@ -174,9 +174,6 @@
       .name.class > span:nth-child(2) {
         margin-left: .4em;
       }
-      .name small {
-        font-weight: normal;
-      }
     .inherited {
       color: #999;
       border-left: 5px solid #eee;

pdoc/templates/html.mako

@@ -181,16 +181,26 @@
       methods = c.methods(show_inherited_members, sort=sort_identifiers)
       mro = c.mro()
       subclasses = c.subclasses()
+      params = ', '.join(c.params(annotate=show_type_annotations))
       %>
       <dt id="${c.refname}"><code class="flex name class">
           <span>class ${ident(c.name)}</span>
-          % if mro:
-              <span>(</span><span><small>ancestors:</small> ${', '.join(link(cls) for cls in mro)})</span>
-          %endif
+          % if params:
+              <span>(</span><span>${params | h})</span>
+          % endif
       </code></dt>
 
       <dd>${show_desc(c)}
 
+      % if mro:
+          <h3>Ancestors</h3>
+          <ul class="hlist">
+          % for cls in mro:
+              <li>${link(cls)}</li>
+          % endfor
+          </ul>
+      %endif
+
       % if subclasses:
           <h3>Subclasses</h3>
           <ul class="hlist">

pdoc/test/__init__.py

@@ -415,12 +415,12 @@ def test__pdoc__dict(self):
             self.assertIn('A', mod.doc)
             self.assertNotIn('B', mod.doc)
 
-        with patch.object(module, '__pdoc__', {'B.__init__': False}):
+        with patch.object(module, '__pdoc__', {'B.f': False}):
             mod = pdoc.Module(module)
             pdoc.link_inheritance()
             self.assertIn('B', mod.doc)
-            self.assertNotIn('__init__', mod.doc['B'].doc)
-            self.assertIsInstance(mod.find_ident('B.__init__'), pdoc.External)
+            self.assertNotIn('f', mod.doc['B'].doc)
+            self.assertIsInstance(mod.find_ident('B.f'), pdoc.External)
 
     def test__pdoc__invalid_value(self):
         module = pdoc.import_module(EXAMPLE_MODULE)
@@ -450,6 +450,10 @@ def test_find_ident(self):
         self.assertIsInstance(result, pdoc.External)
         self.assertEqual(result.name, nonexistent)
 
+        # Ref by class __init__
+        mod = pdoc.Module(pdoc)
+        self.assertIs(mod.find_ident('pdoc.Doc.__init__').obj, pdoc.Doc)
+
     def test_inherits(self):
         module = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
         pdoc.link_inheritance()
@@ -573,6 +577,44 @@ def f() -> typing.List[typing.Union[str, pdoc.Doc]]: pass
         func = pdoc.Function('f', pdoc.Module(pdoc), f)
         self.assertEqual(func.return_annotation, 'List[Union[str,\xA0pdoc.Doc]]')
 
+    @ignore_warnings
+    def test_Class_docstring(self):
+        class A:
+            """foo"""
+
+        class B:
+            def __init__(self):
+                """foo"""
+
+        class C:
+            """foo"""
+            def __init__(self):
+                """bar"""
+
+        class D(C):
+            """baz"""
+
+        class E(C):
+            def __init__(self):
+                """baz"""
+
+        self.assertEqual(pdoc.Class('A', pdoc.Module(pdoc), A).docstring, """foo""")
+        self.assertEqual(pdoc.Class('B', pdoc.Module(pdoc), B).docstring, """foo""")
+        self.assertEqual(pdoc.Class('C', pdoc.Module(pdoc), C).docstring, """foo\n\nbar""")
+        self.assertEqual(pdoc.Class('D', pdoc.Module(pdoc), D).docstring, """baz\n\nbar""")
+        self.assertEqual(pdoc.Class('E', pdoc.Module(pdoc), E).docstring, """foo\n\nbaz""")
+
+    @ignore_warnings
+    def test_Class_params(self):
+        class C:
+            def __init__(self, x):
+                pass
+
+        mod = pdoc.Module(pdoc)
+        self.assertEqual(pdoc.Class('C', mod, C).params(), ['x'])
+        with patch.dict(mod.obj.__pdoc__, {'C.__init__': False}):
+            self.assertEqual(pdoc.Class('C', mod, C).params(), [])
+
     def test_url(self):
         mod = pdoc.Module(pdoc.import_module(EXAMPLE_MODULE))
         pdoc.link_inheritance()