diff options
| -rw-r--r-- | doc/source/_templates/autosummary/class.rst | 23 | ||||
| -rw-r--r-- | doc/source/conf.py | 8 | ||||
| -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 |
6 files changed, 130 insertions, 10 deletions
diff --git a/doc/source/_templates/autosummary/class.rst b/doc/source/_templates/autosummary/class.rst new file mode 100644 index 000000000..15af9822e --- /dev/null +++ b/doc/source/_templates/autosummary/class.rst @@ -0,0 +1,23 @@ +{% extends "!autosummary/class.rst" %} + +{% block methods %} +{% if methods %} + .. HACK + .. autosummary:: + :toctree: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} +{% endif %} +{% endblock %} + +{% block attributes %} +{% if attributes %} + .. HACK + .. autosummary:: + :toctree: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} +{% endif %} +{% endblock %} diff --git a/doc/source/conf.py b/doc/source/conf.py index 318011e8a..1fbd0c60e 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,12 +18,13 @@ sys.path.insert(0, os.path.abspath('../sphinxext')) extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', - 'only_directives', 'plot_directive'] + 'plot_directive'] if sphinx.__version__ >= "0.7": extensions.append('sphinx.ext.autosummary') else: extensions.append('autosummary') + extensions.append('only_directives') # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -250,6 +251,9 @@ np.random.seed(0) plot_include_source = True plot_formats = [('png', 100), 'pdf'] +import math +phi = (math.sqrt(5) + 1)/2 + import matplotlib matplotlib.rcParams.update({ 'font.size': 8, @@ -258,7 +262,7 @@ matplotlib.rcParams.update({ 'xtick.labelsize': 8, 'ytick.labelsize': 8, 'legend.fontsize': 8, - 'figure.figsize': (3.236068, 2), + 'figure.figsize': (3*phi, 3), 'figure.subplot.bottom': 0.2, 'figure.subplot.left': 0.2, 'figure.subplot.right': 0.9, 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) |