docs: generate Attributes and Methods sections in class documentation

4 files changed, 101 insertions, 8 deletions

diff --git a/doc/sphinxext/README.txt b/doc/sphinxext/README.txt
new file mode 100644
index 000000000..20aaac22f
--- /dev/null
+++ b/doc/sphinxext/README.txt
@@ -0,0 +1,24 @@
+=====================================
+numpydoc -- Numpy's Sphinx extensions
+=====================================
+
+Numpy's documentation uses several custom extensions to Sphinx.  These
+are shipped in this ``numpydoc`` package, in case you want to make use
+of tem in third-party projects.
+
+The following extensions are available:
+
+  - ``numpydoc``: support for the Numpy docstring format in Sphinx.
+
+  - ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes.
+
+  - ``numpydoc.plot_directives``: Adaptation of Matplotlib's ``plot::``
+    directive. Note that this implementation may still undergo severe
+    changes or be eventually deprecated.
+
+  - ``numpydoc.only_directives``: (DEPRECATED)
+
+  - ``numpydoc.autosummary``: (DEPRECATED) An ``autosummary::`` directive.
+    Available in Sphinx 0.6.2 and (to-be) 1.0 as ``sphinx.ext.autosummary``,
+    and it the Sphinx 1.0 version is recommended over that included in
+    Numpydoc.
diff --git a/doc/sphinxext/docscrape.py b/doc/sphinxext/docscrape.py
index f374b3ddc..3e190b6f2 100644
--- a/doc/sphinxext/docscrape.py
+++ b/doc/sphinxext/docscrape.py
@@ -8,7 +8,7 @@ import re
 import pydoc
 from StringIO import StringIO
 from warnings import warn
-4
+
 class Reader(object):
     """A line-based string reader.
 
@@ -386,6 +386,8 @@ class NumpyDocString(object):
         out += self._str_see_also(func_role)
         for s in ('Notes','References','Examples'):
             out += self._str_section(s)
+        for param_list in ('Attributes', 'Methods'):
+            out += self._str_param_list(param_list)
         out += self._str_index()
         return '\n'.join(out)
 
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)
diff --git a/doc/sphinxext/plot_directive.py b/doc/sphinxext/plot_directive.py
index f564cd670..8de8c7399 100644
--- a/doc/sphinxext/plot_directive.py
+++ b/doc/sphinxext/plot_directive.py
@@ -73,6 +73,7 @@ TODO
 """
 
 import sys, os, glob, shutil, imp, warnings, cStringIO, re, textwrap, traceback
+import sphinx
 
 import warnings
 warnings.warn("A plot_directive module is also available under "
@@ -157,7 +158,7 @@ except ImportError:
 TEMPLATE = """
 {{ source_code }}
 
-.. htmlonly::
+{{ only_html }}
 
    {% if source_code %}
    (`Source code <{{ source_link }}>`__)
@@ -188,7 +189,7 @@ TEMPLATE = """
           )
        {% endfor %}
 
-.. latexonly::
+{{ only_latex }}
 
    {% for img in images %}
    .. image:: {{ build_dir }}/{{ img.basename }}.pdf
@@ -304,11 +305,20 @@ def run(arguments, content, options, state_machine, state, lineno):
     opts = [':%s: %s' % (key, val) for key, val in options.items()
             if key in ('alt', 'height', 'width', 'scale', 'align', 'class')]
 
+    if sphinx.__version__ >= "0.6":
+        only_html = ".. only:: html"
+        only_latex = ".. only:: latex"
+    else:
+        only_html = ".. htmlonly::"
+        only_latex = ".. latexonly::"
+
     result = format_template(
         TEMPLATE,
         dest_dir=dest_dir_link,
         build_dir=build_dir_link,
         source_link=source_link,
+        only_html=only_html,
+        only_latex=only_latex,
         options=opts,
         images=images,
         source_code=source_code)