From 692f3f65acd441995f893908d694b3891a67070c Mon Sep 17 00:00:00 2001
From: Pauli Virtanen <pav@iki.fi>
Date: Sat, 27 Jun 2009 15:02:14 +0000
Subject: docs: generate Attributes and Methods sections in class documentation

---
 doc/sphinxext/docscrape_sphinx.py | 67 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 5 deletions(-)

(limited to 'doc/sphinxext/docscrape_sphinx.py')

diff --git a/doc/sphinxext/docscrape_sphinx.py b/doc/sphinxext/docscrape_sphinx.py
index 5b60567b3..1747ae0db 100644
--- a/doc/sphinxext/docscrape_sphinx.py
+++ b/doc/sphinxext/docscrape_sphinx.py
@@ -44,6 +44,58 @@ class SphinxDocString(NumpyDocString):
                 out += ['']
         return out
 
+    @property
+    def _obj(self):
+        if hasattr(self, '_cls'):
+            return self._cls
+        elif hasattr(self, '_f'):
+            return self._f
+        return None
+
+    def _str_member_list(self, name):
+        """
+        Generate a member listing, autosummary:: table where possible,
+        and a table where not.
+
+        """
+        out = []
+        if self[name]:
+            out += ['.. rubric:: %s' % name, '']
+            prefix = getattr(self, '_name', '')
+
+            if prefix:
+                prefix = '~%s.' % prefix
+
+            autosum = []
+            others = []
+            for param, param_type, desc in self[name]:
+                param = param.strip()
+                if not self._obj or \
+                       (hasattr(self._obj, param) and
+                        getattr(getattr(self._obj, param), '__doc__', None)):
+                    autosum += ["   %s%s" % (prefix, param)]
+                else:
+                    others.append((param, param_type, desc))
+
+            if autosum:
+                out += ['.. autosummary::', '   :toctree:', '']
+                out += autosum
+
+            if others:
+                maxlen_0 = max([len(x[0]) for x in others])
+                maxlen_1 = max([len(x[1]) for x in others])
+                hdr = "="*maxlen_0 + "  " + "="*maxlen_1 + "  " + "="*10
+                fmt = '%%%ds  %%%ds  ' % (maxlen_0, maxlen_1)
+                n_indent = maxlen_0 + maxlen_1 + 4
+                out += [hdr]
+                for param, param_type, desc in others:
+                    out += [fmt % (param.strip(), param_type)]
+                    out += self._str_indent(desc, n_indent)
+                out += [hdr]
+            out += ['']
+            print "\n".join(out)
+        return out
+
     def _str_section(self, name):
         out = []
         if self[name]:
@@ -95,7 +147,7 @@ class SphinxDocString(NumpyDocString):
             out += ['']
             # Latex collects all references to a separate bibliography,
             # so we need to insert links to it
-            if sphinx.__version__ >= 0.6:
+            if sphinx.__version__ >= "0.6":
                 out += ['.. only:: latex','']
             else:
                 out += ['.. latexonly::','']
@@ -127,14 +179,15 @@ class SphinxDocString(NumpyDocString):
         out += self._str_index() + ['']
         out += self._str_summary()
         out += self._str_extended_summary()
-        for param_list in ('Parameters', 'Attributes', 'Methods',
-                           'Returns','Raises'):
+        for param_list in ('Parameters', 'Returns', 'Raises'):
             out += self._str_param_list(param_list)
         out += self._str_warnings()
         out += self._str_see_also(func_role)
         out += self._str_section('Notes')
         out += self._str_references()
         out += self._str_examples()
+        for param_list in ('Attributes', 'Methods'):
+            out += self._str_member_list(param_list)
         out = self._str_indent(out,indent)
         return '\n'.join(out)
 
@@ -144,6 +197,11 @@ class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
 class SphinxClassDoc(SphinxDocString, ClassDoc):
     pass
 
+class SphinxObjDoc(SphinxDocString):
+    def __init__(self, obj, doc):
+        self._f = obj
+        SphinxDocString.__init__(self, doc)
+
 def get_doc_object(obj, what=None, doc=None):
     if what is None:
         if inspect.isclass(obj):
@@ -161,5 +219,4 @@ def get_doc_object(obj, what=None, doc=None):
     else:
         if doc is None:
             doc = pydoc.getdoc(obj)
-        return SphinxDocString(doc)
-
+        return SphinxObjDoc(obj, doc)
-- 
cgit v1.2.1