Changeset 8f0b82 for doc/sphinxext/docscrape_sphinx.py

Timestamp:

10/04/10 11:40:47 (3 years ago)

Author:

Tiago de Paula Peixoto <tiago@…>

Branches:

master, python3

Children:

cab630

Parents:

561521

git-author:

Tiago de Paula Peixoto <tiago@…> (10/03/10 23:40:49)

git-committer:

Tiago de Paula Peixoto <tiago@…> (10/04/10 11:40:47)

Message:

Replace jsmath with MathJax and update sphinxext

File:

• doc/sphinxext/docscrape_sphinx.py (modified) (6 diffs)

doc/sphinxext/docscrape_sphinx.py

@@ -1 +1 @@
 import re, inspect, textwrap, pydoc
+import sphinx
 from docscrape import NumpyDocString, FunctionDoc, ClassDoc
 
 class SphinxDocString(NumpyDocString):
+    def __init__(self, docstring, config={}):
+        self.use_plots = config.get('use_plots', False)
+        NumpyDocString.__init__(self, docstring, config=config)
+
     # string conversion routines
     def _str_header(self, name, symbol='`'):
@@ -40 +45 @@
                 out += self._str_indent(desc,8)
                 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):
+                    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 += ['']
         return out
 
@@ -91 +145 @@
             out.extend(self['References'])
             out += ['']
-        return out
+            # Latex collects all references to a separate bibliography,
+            # so we need to insert links to it
+            if sphinx.__version__ >= "0.6":
+                out += ['.. only:: latex','']
+            else:
+                out += ['.. latexonly::','']
+            items = []
+            for line in self['References']:
+                m = re.match(r'.. \[([a-z0-9._-]+)\]', line, re.I)
+                if m:
+                    items.append(m.group(1))
+            out += ['   ' + ", ".join(["[%s]_" % item for item in items]), '']
+        return out
+
+    def _str_examples(self):
+        examples_str = "\n".join(self['Examples'])
+
+        if (self.use_plots and 'import matplotlib' in examples_str
+                and 'plot::' not in examples_str):
+            out = []
+            out += self._str_header('Examples')
+            out += ['.. plot::', '']
+            out += self._str_indent(self['Examples'])
+            out += ['']
+            return out
+        else:
+            return self._str_section('Examples')
 
     def __str__(self, indent=0, func_role="obj"):
@@ -99 +179 @@
         out += self._str_summary()
         out += self._str_extended_summary()
-        for param_list in ('Parameters', 'Attributes', 'Methods',
-                           'Returns','Raises'):
+        for param_list in ('Parameters', 'Returns', 'Other Parameters',
+                           'Raises', 'Warns'):
             out += self._str_param_list(param_list)
         out += self._str_warnings()
@@ -106 +186 @@
         out += self._str_section('Notes')
         out += self._str_references()
-        out += self._str_section('Examples')
+        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)
 
 class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
-    pass
+    def __init__(self, obj, doc=None, config={}):
+        self.use_plots = config.get('use_plots', False)
+        FunctionDoc.__init__(self, obj, doc=doc, config=config)
 
 class SphinxClassDoc(SphinxDocString, ClassDoc):
-    pass
-
-def get_doc_object(obj, what=None):
+    def __init__(self, obj, doc=None, func_doc=None, config={}):
+        self.use_plots = config.get('use_plots', False)
+        ClassDoc.__init__(self, obj, doc=doc, func_doc=None, config=config)
+
+class SphinxObjDoc(SphinxDocString):
+    def __init__(self, obj, doc=None, config={}):
+        self._f = obj
+        SphinxDocString.__init__(self, doc, config=config)
+
+def get_doc_object(obj, what=None, doc=None, config={}):
     if what is None:
         if inspect.isclass(obj):
@@ -127 +218 @@
             what = 'object'
     if what == 'class':
-        return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc)
+        return SphinxClassDoc(obj, func_doc=SphinxFunctionDoc, doc=doc,
+                              config=config)
     elif what in ('function', 'method'):
-        return SphinxFunctionDoc(obj, '')
+        return SphinxFunctionDoc(obj, doc=doc, config=config)
     else:
-        return SphinxDocString(pydoc.getdoc(obj))
+        if doc is None:
+            doc = pydoc.getdoc(obj)
+        return SphinxObjDoc(obj, doc, config=config)