diff options
Diffstat (limited to 'doc/sphinxext')
| -rw-r--r-- | doc/sphinxext/README.txt | 24 | ||||
| -rw-r--r-- | doc/sphinxext/docscrape.py | 4 | ||||
| -rw-r--r-- | doc/sphinxext/docscrape_sphinx.py | 67 | ||||
| -rw-r--r-- | doc/sphinxext/plot_directive.py | 14 |
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) |