diff --git a/ci/deps/travis-36-doc.yaml b/ci/deps/travis-36-doc.yaml index ed0764fab414a..c345af0a2983c 100644 --- a/ci/deps/travis-36-doc.yaml +++ b/ci/deps/travis-36-doc.yaml @@ -21,6 +21,7 @@ dependencies: - notebook - numexpr - numpy=1.13* + - numpydoc - openpyxl - pandoc - pyarrow diff --git a/doc/source/conf.py b/doc/source/conf.py index 56f77f667df88..bbc4320433650 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,7 +18,10 @@ import importlib import logging import warnings + from sphinx.ext.autosummary import _import_by_name +from numpydoc.docscrape import NumpyDocString +from numpydoc.docscrape_sphinx import SphinxDocString logger = logging.getLogger(__name__) @@ -49,10 +52,6 @@ ]) -# numpydoc is available in the sphinxext directory, and can't be imported -# until sphinxext is available in the Python path -from numpydoc.docscrape import NumpyDocString - # -- General configuration ----------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be @@ -64,7 +63,7 @@ 'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'sphinx.ext.todo', - 'numpydoc', + 'numpydoc', # handle NumPy documentation formatted docstrings 'IPython.sphinxext.ipython_directive', 'IPython.sphinxext.ipython_console_highlighting', 'matplotlib.sphinxext.plot_directive', @@ -102,12 +101,6 @@ if any(re.match(r"\s*api\s*", l) for l in index_rst_lines): autosummary_generate = True -# numpydoc -# for now use old parameter listing (styling + **kwargs problem) -numpydoc_use_blockquotes = True -# use member listing for attributes -numpydoc_attributes_as_param_list = False - # matplotlib plot directive plot_include_source = True plot_formats = [("png", 90)] @@ -420,6 +413,62 @@ ] +def sphinxdocstring_str(self, indent=0, func_role="obj"): + # Pandas displays Attributes section in style like Methods section + + # Function is copy of `SphinxDocString.__str__` + ns = { + 'signature': self._str_signature(), + 'index': self._str_index(), + 'summary': self._str_summary(), + 'extended_summary': self._str_extended_summary(), + 'parameters': self._str_param_list('Parameters'), + 'returns': self._str_returns('Returns'), + 'yields': self._str_returns('Yields'), + 'other_parameters': self._str_param_list('Other Parameters'), + 'raises': self._str_param_list('Raises'), + 'warns': self._str_param_list('Warns'), + 'warnings': self._str_warnings(), + 'see_also': self._str_see_also(func_role), + 'notes': self._str_section('Notes'), + 'references': self._str_references(), + 'examples': self._str_examples(), + # Replaced `self._str_param_list('Attributes', fake_autosummary=True)` + # with `self._str_member_list('Attributes')` + 'attributes': self._str_member_list('Attributes'), + 'methods': self._str_member_list('Methods'), + } + ns = {k: '\n'.join(v) for k, v in ns.items()} + + rendered = self.template.render(**ns) + return '\n'.join(self._str_indent(rendered.split('\n'), indent)) + + +SphinxDocString.__str__ = sphinxdocstring_str + + +# Fix "WARNING: Inline strong start-string without end-string." +# PR #155 "Escape the * in *args and **kwargs" from numpydoc +# Can be removed after PR merges in v0.9.0 +def decorate_process_param(func): + def _escape_args_and_kwargs(name): + if name[:2] == '**': + return r'\*\*' + name[2:] + elif name[:1] == '*': + return r'\*' + name[1:] + else: + return name + + def func_wrapper(self, param, desc, fake_autosummary): + param = _escape_args_and_kwargs(param.strip()) + return func(self, param, desc, fake_autosummary) + + return func_wrapper + + +func = SphinxDocString._process_param +SphinxDocString._process_param = decorate_process_param(func) + # Add custom Documenter to handle attributes/methods of an AccessorProperty # eg pandas.Series.str and pandas.Series.dt (see GH9322) diff --git a/doc/sphinxext/numpydoc/LICENSE.txt b/doc/sphinxext/numpydoc/LICENSE.txt deleted file mode 100644 index b15c699dcecaa..0000000000000 --- a/doc/sphinxext/numpydoc/LICENSE.txt +++ /dev/null @@ -1,94 +0,0 @@ -------------------------------------------------------------------------------- - The files - - numpydoc.py - - docscrape.py - - docscrape_sphinx.py - - phantom_import.py - have the following license: - -Copyright (C) 2008 Stefan van der Walt , Pauli Virtanen - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, -INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. - -------------------------------------------------------------------------------- - The files - - compiler_unparse.py - - comment_eater.py - - traitsdoc.py - have the following license: - -This software is OSI Certified Open Source Software. -OSI Certified is a certification mark of the Open Source Initiative. - -Copyright (c) 2006, Enthought, Inc. -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - * Neither the name of Enthought, Inc. nor the names of its contributors may - be used to endorse or promote products derived from this software without - specific prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - - -------------------------------------------------------------------------------- - The file - - plot_directive.py - originates from Matplotlib (http://matplotlib.sf.net/) which has - the following license: - -Copyright (c) 2002-2008 John D. Hunter; All Rights Reserved. - -1. This LICENSE AGREEMENT is between John D. Hunter (“JDH”), and the Individual or Organization (“Licensee”) accessing and otherwise using matplotlib software in source or binary form and its associated documentation. - -2. Subject to the terms and conditions of this License Agreement, JDH hereby grants Licensee a nonexclusive, royalty-free, world-wide license to reproduce, analyze, test, perform and/or display publicly, prepare derivative works, distribute, and otherwise use matplotlib 0.98.3 alone or in any derivative version, provided, however, that JDH’s License Agreement and JDH’s notice of copyright, i.e., “Copyright (c) 2002-2008 John D. Hunter; All Rights Reserved” are retained in matplotlib 0.98.3 alone or in any derivative version prepared by Licensee. - -3. In the event Licensee prepares a derivative work that is based on or incorporates matplotlib 0.98.3 or any part thereof, and wants to make the derivative work available to others as provided herein, then Licensee hereby agrees to include in any such work a brief summary of the changes made to matplotlib 0.98.3. - -4. JDH is making matplotlib 0.98.3 available to Licensee on an “AS IS” basis. JDH MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, JDH MAKES NO AND DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF MATPLOTLIB 0.98.3 WILL NOT INFRINGE ANY THIRD PARTY RIGHTS. - -5. JDH SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF MATPLOTLIB 0.98.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING MATPLOTLIB 0.98.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. - -6. This License Agreement will automatically terminate upon a material breach of its terms and conditions. - -7. Nothing in this License Agreement shall be deemed to create any relationship of agency, partnership, or joint venture between JDH and Licensee. This License Agreement does not grant permission to use JDH trademarks or trade name in a trademark sense to endorse or promote products or services of Licensee, or any third party. - -8. By copying, installing or otherwise using matplotlib 0.98.3, Licensee agrees to be bound by the terms and conditions of this License Agreement. - diff --git a/doc/sphinxext/numpydoc/README.rst b/doc/sphinxext/numpydoc/README.rst deleted file mode 100755 index f91811ef9add6..0000000000000 --- a/doc/sphinxext/numpydoc/README.rst +++ /dev/null @@ -1,51 +0,0 @@ -===================================== -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 them in third-party projects. - -The following extensions are available: - - - ``numpydoc``: support for the Numpy docstring format in Sphinx, and add - the code description directives ``np:function``, ``np-c:function``, etc. - that support the Numpy docstring syntax. - - - ``numpydoc.traitsdoc``: For gathering documentation about Traits attributes. - - - ``numpydoc.plot_directive``: Adaptation of Matplotlib's ``plot::`` - directive. Note that this implementation may still undergo severe - changes or eventually be deprecated. - - -numpydoc -======== - -Numpydoc inserts a hook into Sphinx's autodoc that converts docstrings -following the Numpy/Scipy format to a form palatable to Sphinx. - -Options -------- - -The following options can be set in conf.py: - -- numpydoc_use_plots: bool - - Whether to produce ``plot::`` directives for Examples sections that - contain ``import matplotlib``. - -- numpydoc_show_class_members: bool - - Whether to show all members of a class in the Methods and Attributes - sections automatically. - -- numpydoc_class_members_toctree: bool - - Whether to create a Sphinx table of contents for the lists of class - methods and attributes. If a table of contents is made, Sphinx expects - each entry to have a separate page. - -- numpydoc_edit_link: bool (DEPRECATED -- edit your HTML template instead) - - Whether to insert an edit link after docstrings. diff --git a/doc/sphinxext/numpydoc/__init__.py b/doc/sphinxext/numpydoc/__init__.py deleted file mode 100644 index 30dba8fcf9132..0000000000000 --- a/doc/sphinxext/numpydoc/__init__.py +++ /dev/null @@ -1,8 +0,0 @@ -from __future__ import division, absolute_import, print_function - -__version__ = '0.8.0.dev0' - - -def setup(app, *args, **kwargs): - from .numpydoc import setup - return setup(app, *args, **kwargs) diff --git a/doc/sphinxext/numpydoc/docscrape.py b/doc/sphinxext/numpydoc/docscrape.py deleted file mode 100644 index 598b4438ffabc..0000000000000 --- a/doc/sphinxext/numpydoc/docscrape.py +++ /dev/null @@ -1,624 +0,0 @@ -"""Extract reference documentation from the NumPy source tree. - -""" -from __future__ import division, absolute_import, print_function - -import inspect -import textwrap -import re -import pydoc -from warnings import warn -import collections -import copy -import sys - - -def strip_blank_lines(l): - "Remove leading and trailing blank lines from a list of lines" - while l and not l[0].strip(): - del l[0] - while l and not l[-1].strip(): - del l[-1] - return l - - -class Reader(object): - """A line-based string reader. - - """ - def __init__(self, data): - """ - Parameters - ---------- - data : str - String with lines separated by '\n'. - - """ - if isinstance(data, list): - self._str = data - else: - self._str = data.split('\n') # store string as list of lines - - self.reset() - - def __getitem__(self, n): - return self._str[n] - - def reset(self): - self._l = 0 # current line nr - - def read(self): - if not self.eof(): - out = self[self._l] - self._l += 1 - return out - else: - return '' - - def seek_next_non_empty_line(self): - for l in self[self._l:]: - if l.strip(): - break - else: - self._l += 1 - - def eof(self): - return self._l >= len(self._str) - - def read_to_condition(self, condition_func): - start = self._l - for line in self[start:]: - if condition_func(line): - return self[start:self._l] - self._l += 1 - if self.eof(): - return self[start:self._l+1] - return [] - - def read_to_next_empty_line(self): - self.seek_next_non_empty_line() - - def is_empty(line): - return not line.strip() - - return self.read_to_condition(is_empty) - - def read_to_next_unindented_line(self): - def is_unindented(line): - return (line.strip() and (len(line.lstrip()) == len(line))) - return self.read_to_condition(is_unindented) - - def peek(self, n=0): - if self._l + n < len(self._str): - return self[self._l + n] - else: - return '' - - def is_empty(self): - return not ''.join(self._str).strip() - - -class ParseError(Exception): - def __str__(self): - message = self.args[0] - if hasattr(self, 'docstring'): - message = "%s in %r" % (message, self.docstring) - return message - - -class NumpyDocString(collections.Mapping): - """Parses a numpydoc string to an abstract representation - - Instances define a mapping from section title to structured data. - - """ - - sections = { - 'Signature': '', - 'Summary': [''], - 'Extended Summary': [], - 'Parameters': [], - 'Returns': [], - 'Yields': [], - 'Raises': [], - 'Warns': [], - 'Other Parameters': [], - 'Attributes': [], - 'Methods': [], - 'See Also': [], - 'Notes': [], - 'Warnings': [], - 'References': '', - 'Examples': '', - 'index': {} - } - - def __init__(self, docstring, config={}): - orig_docstring = docstring - docstring = textwrap.dedent(docstring).split('\n') - - self._doc = Reader(docstring) - self._parsed_data = copy.deepcopy(self.sections) - - try: - self._parse() - except ParseError as e: - e.docstring = orig_docstring - raise - - def __getitem__(self, key): - return self._parsed_data[key] - - def __setitem__(self, key, val): - if key not in self._parsed_data: - self._error_location("Unknown section %s" % key, error=False) - else: - self._parsed_data[key] = val - - def __iter__(self): - return iter(self._parsed_data) - - def __len__(self): - return len(self._parsed_data) - - def _is_at_section(self): - self._doc.seek_next_non_empty_line() - - if self._doc.eof(): - return False - - l1 = self._doc.peek().strip() # e.g. Parameters - - if l1.startswith('.. index::'): - return True - - l2 = self._doc.peek(1).strip() # ---------- or ========== - return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1)) - - def _strip(self, doc): - i = 0 - j = 0 - for i, line in enumerate(doc): - if line.strip(): - break - - for j, line in enumerate(doc[::-1]): - if line.strip(): - break - - return doc[i:len(doc)-j] - - def _read_to_next_section(self): - section = self._doc.read_to_next_empty_line() - - while not self._is_at_section() and not self._doc.eof(): - if not self._doc.peek(-1).strip(): # previous line was empty - section += [''] - - section += self._doc.read_to_next_empty_line() - - return section - - def _read_sections(self): - while not self._doc.eof(): - data = self._read_to_next_section() - name = data[0].strip() - - if name.startswith('..'): # index section - yield name, data[1:] - elif len(data) < 2: - yield StopIteration - else: - yield name, self._strip(data[2:]) - - def _parse_param_list(self, content): - r = Reader(content) - params = [] - while not r.eof(): - header = r.read().strip() - if ' : ' in header: - arg_name, arg_type = header.split(' : ')[:2] - else: - arg_name, arg_type = header, '' - - desc = r.read_to_next_unindented_line() - desc = dedent_lines(desc) - desc = strip_blank_lines(desc) - - params.append((arg_name, arg_type, desc)) - - return params - - _name_rgx = re.compile(r"^\s*(:(?P\w+):" - r"`(?P(?:~\w+\.)?[a-zA-Z0-9_.-]+)`|" - r" (?P[a-zA-Z0-9_.-]+))\s*", re.X) - - def _parse_see_also(self, content): - """ - func_name : Descriptive text - continued text - another_func_name : Descriptive text - func_name1, func_name2, :meth:`func_name`, func_name3 - - """ - items = [] - - def parse_item_name(text): - """Match ':role:`name`' or 'name'""" - m = self._name_rgx.match(text) - if m: - g = m.groups() - if g[1] is None: - return g[3], None - else: - return g[2], g[1] - raise ParseError("%s is not a item name" % text) - - def push_item(name, rest): - if not name: - return - name, role = parse_item_name(name) - items.append((name, list(rest), role)) - del rest[:] - - current_func = None - rest = [] - - for line in content: - if not line.strip(): - continue - - m = self._name_rgx.match(line) - if m and line[m.end():].strip().startswith(':'): - push_item(current_func, rest) - current_func, line = line[:m.end()], line[m.end():] - rest = [line.split(':', 1)[1].strip()] - if not rest[0]: - rest = [] - elif not line.startswith(' '): - push_item(current_func, rest) - current_func = None - if ',' in line: - for func in line.split(','): - if func.strip(): - push_item(func, []) - elif line.strip(): - current_func = line - elif current_func is not None: - rest.append(line.strip()) - push_item(current_func, rest) - return items - - def _parse_index(self, section, content): - """ - .. index: default - :refguide: something, else, and more - - """ - def strip_each_in(lst): - return [s.strip() for s in lst] - - out = {} - section = section.split('::') - if len(section) > 1: - out['default'] = strip_each_in(section[1].split(','))[0] - for line in content: - line = line.split(':') - if len(line) > 2: - out[line[1]] = strip_each_in(line[2].split(',')) - return out - - def _parse_summary(self): - """Grab signature (if given) and summary""" - if self._is_at_section(): - return - - # If several signatures present, take the last one - while True: - summary = self._doc.read_to_next_empty_line() - summary_str = " ".join([s.strip() for s in summary]).strip() - if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str): - self['Signature'] = summary_str - if not self._is_at_section(): - continue - break - - if summary is not None: - self['Summary'] = summary - - if not self._is_at_section(): - self['Extended Summary'] = self._read_to_next_section() - - def _parse(self): - self._doc.reset() - self._parse_summary() - - sections = list(self._read_sections()) - section_names = set([section for section, content in sections]) - - has_returns = 'Returns' in section_names - has_yields = 'Yields' in section_names - # We could do more tests, but we are not. Arbitrarily. - if has_returns and has_yields: - msg = 'Docstring contains both a Returns and Yields section.' - raise ValueError(msg) - - for (section, content) in sections: - if not section.startswith('..'): - section = (s.capitalize() for s in section.split(' ')) - section = ' '.join(section) - if self.get(section): - self._error_location("The section %s appears twice" - % section) - - if section in ('Parameters', 'Returns', 'Yields', 'Raises', - 'Warns', 'Other Parameters', 'Attributes', - 'Methods'): - self[section] = self._parse_param_list(content) - elif section.startswith('.. index::'): - self['index'] = self._parse_index(section, content) - elif section == 'See Also': - self['See Also'] = self._parse_see_also(content) - else: - self[section] = content - - def _error_location(self, msg, error=True): - if hasattr(self, '_obj'): - # we know where the docs came from: - try: - filename = inspect.getsourcefile(self._obj) - except TypeError: - filename = None - msg = msg + (" in the docstring of %s in %s." - % (self._obj, filename)) - if error: - raise ValueError(msg) - else: - warn(msg) - - # string conversion routines - - def _str_header(self, name, symbol='-'): - return [name, len(name)*symbol] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - if self['Signature']: - return [self['Signature'].replace('*', '\*')] + [''] - else: - return [''] - - def _str_summary(self): - if self['Summary']: - return self['Summary'] + [''] - else: - return [] - - def _str_extended_summary(self): - if self['Extended Summary']: - return self['Extended Summary'] + [''] - else: - return [] - - def _str_param_list(self, name): - out = [] - if self[name]: - out += self._str_header(name) - for param, param_type, desc in self[name]: - if param_type: - out += ['%s : %s' % (param, param_type)] - else: - out += [param] - if desc and ''.join(desc).strip(): - out += self._str_indent(desc) - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - out += self[name] - out += [''] - return out - - def _str_see_also(self, func_role): - if not self['See Also']: - return [] - out = [] - out += self._str_header("See Also") - last_had_desc = True - for func, desc, role in self['See Also']: - if role: - link = ':%s:`%s`' % (role, func) - elif func_role: - link = ':%s:`%s`' % (func_role, func) - else: - link = "`%s`_" % func - if desc or last_had_desc: - out += [''] - out += [link] - else: - out[-1] += ", %s" % link - if desc: - out += self._str_indent([' '.join(desc)]) - last_had_desc = True - else: - last_had_desc = False - out += [''] - return out - - def _str_index(self): - idx = self['index'] - out = [] - out += ['.. index:: %s' % idx.get('default', '')] - for section, references in idx.items(): - if section == 'default': - continue - out += [' :%s: %s' % (section, ', '.join(references))] - return out - - def __str__(self, func_role=''): - out = [] - out += self._str_signature() - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters', 'Returns', 'Yields', - 'Other Parameters', 'Raises', 'Warns'): - out += self._str_param_list(param_list) - out += self._str_section('Warnings') - 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) - - -def indent(str, indent=4): - indent_str = ' '*indent - if str is None: - return indent_str - lines = str.split('\n') - return '\n'.join(indent_str + l for l in lines) - - -def dedent_lines(lines): - """Deindent a list of lines maximally""" - return textwrap.dedent("\n".join(lines)).split("\n") - - -def header(text, style='-'): - return text + '\n' + style*len(text) + '\n' - - -class FunctionDoc(NumpyDocString): - def __init__(self, func, role='func', doc=None, config={}): - self._f = func - self._role = role # e.g. "func" or "meth" - - if doc is None: - if func is None: - raise ValueError("No function or docstring given") - doc = inspect.getdoc(func) or '' - NumpyDocString.__init__(self, doc) - - if not self['Signature'] and func is not None: - func, func_name = self.get_func() - try: - try: - signature = str(inspect.signature(func)) - except (AttributeError, ValueError): - # try to read signature, backward compat for older Python - if sys.version_info[0] >= 3: - argspec = inspect.getfullargspec(func) - else: - argspec = inspect.getargspec(func) - signature = inspect.formatargspec(*argspec) - signature = '%s%s' % (func_name, signature.replace('*', '\*')) - except TypeError: - signature = '%s()' % func_name - self['Signature'] = signature - - def get_func(self): - func_name = getattr(self._f, '__name__', self.__class__.__name__) - if inspect.isclass(self._f): - func = getattr(self._f, '__call__', self._f.__init__) - else: - func = self._f - return func, func_name - - def __str__(self): - out = '' - - func, func_name = self.get_func() - signature = self['Signature'].replace('*', '\*') - - roles = {'func': 'function', - 'meth': 'method'} - - if self._role: - if self._role not in roles: - print("Warning: invalid role %s" % self._role) - out += '.. %s:: %s\n \n\n' % (roles.get(self._role, ''), - func_name) - - out += super(FunctionDoc, self).__str__(func_role=self._role) - return out - - -class ClassDoc(NumpyDocString): - - extra_public_methods = ['__call__'] - - def __init__(self, cls, doc=None, modulename='', func_doc=FunctionDoc, - config={}): - if not inspect.isclass(cls) and cls is not None: - raise ValueError("Expected a class or None, but got %r" % cls) - self._cls = cls - - self.show_inherited_members = config.get( - 'show_inherited_class_members', True) - - if modulename and not modulename.endswith('.'): - modulename += '.' - self._mod = modulename - - if doc is None: - if cls is None: - raise ValueError("No class or documentation string given") - doc = pydoc.getdoc(cls) - - NumpyDocString.__init__(self, doc) - - if config.get('show_class_members', True): - def splitlines_x(s): - if not s: - return [] - else: - return s.splitlines() - - for field, items in [('Methods', self.methods), - ('Attributes', self.properties)]: - if not self[field]: - doc_list = [] - for name in sorted(items): - try: - doc_item = pydoc.getdoc(getattr(self._cls, name)) - doc_list.append((name, '', splitlines_x(doc_item))) - except AttributeError: - pass # method doesn't exist - self[field] = doc_list - - @property - def methods(self): - if self._cls is None: - return [] - return [name for name, func in inspect.getmembers(self._cls) - if ((not name.startswith('_') - or name in self.extra_public_methods) - and isinstance(func, collections.Callable) - and self._is_show_member(name))] - - @property - def properties(self): - if self._cls is None: - return [] - return [name for name, func in inspect.getmembers(self._cls) - if (not name.startswith('_') and - (func is None or isinstance(func, property) or - inspect.isdatadescriptor(func)) - and self._is_show_member(name))] - - def _is_show_member(self, name): - if self.show_inherited_members: - return True # show all class members - if name not in self._cls.__dict__: - return False # class member is inherited, we do not show it - return True diff --git a/doc/sphinxext/numpydoc/docscrape_sphinx.py b/doc/sphinxext/numpydoc/docscrape_sphinx.py deleted file mode 100644 index 19c355eba1898..0000000000000 --- a/doc/sphinxext/numpydoc/docscrape_sphinx.py +++ /dev/null @@ -1,429 +0,0 @@ -from __future__ import division, absolute_import, print_function - -import sys -import re -import inspect -import textwrap -import pydoc -import collections -import os - -from jinja2 import FileSystemLoader -from jinja2.sandbox import SandboxedEnvironment -import sphinx -from sphinx.jinja2glue import BuiltinTemplateLoader - -from .docscrape import NumpyDocString, FunctionDoc, ClassDoc - -if sys.version_info[0] >= 3: - sixu = lambda s: s -else: - sixu = lambda s: unicode(s, 'unicode_escape') - - -IMPORT_MATPLOTLIB_RE = r'\b(import +matplotlib|from +matplotlib +import)\b' - - -class SphinxDocString(NumpyDocString): - def __init__(self, docstring, config={}): - NumpyDocString.__init__(self, docstring, config=config) - self.load_config(config) - - def load_config(self, config): - self.use_plots = config.get('use_plots', False) - self.use_blockquotes = config.get('use_blockquotes', False) - self.class_members_toctree = config.get('class_members_toctree', True) - self.attributes_as_param_list = config.get('attributes_as_param_list', True) - self.template = config.get('template', None) - if self.template is None: - template_dirs = [os.path.join(os.path.dirname(__file__), 'templates')] - template_loader = FileSystemLoader(template_dirs) - template_env = SandboxedEnvironment(loader=template_loader) - self.template = template_env.get_template('numpydoc_docstring.rst') - - # string conversion routines - def _str_header(self, name, symbol='`'): - return ['.. rubric:: ' + name, ''] - - def _str_field_list(self, name): - return [':' + name + ':'] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - return [''] - if self['Signature']: - return ['``%s``' % self['Signature']] + [''] - else: - return [''] - - def _str_summary(self): - return self['Summary'] + [''] - - def _str_extended_summary(self): - return self['Extended Summary'] + [''] - - def _str_returns(self, name='Returns'): - if self.use_blockquotes: - typed_fmt = '**%s** : %s' - untyped_fmt = '**%s**' - else: - typed_fmt = '%s : %s' - untyped_fmt = '%s' - - out = [] - if self[name]: - out += self._str_field_list(name) - out += [''] - for param, param_type, desc in self[name]: - if param_type: - out += self._str_indent([typed_fmt % (param.strip(), - param_type)]) - else: - out += self._str_indent([untyped_fmt % param.strip()]) - if desc and self.use_blockquotes: - out += [''] - elif not desc: - desc = ['..'] - out += self._str_indent(desc, 8) - out += [''] - return out - - def _process_param(self, param, desc, fake_autosummary): - """Determine how to display a parameter - - Emulates autosummary behavior if fake_autosummary - - Parameters - ---------- - param : str - The name of the parameter - desc : list of str - The parameter description as given in the docstring. This is - ignored when autosummary logic applies. - fake_autosummary : bool - If True, autosummary-style behaviour will apply for params - that are attributes of the class and have a docstring. - - Returns - ------- - display_param : str - The marked up parameter name for display. This may include a link - to the corresponding attribute's own documentation. - desc : list of str - A list of description lines. This may be identical to the input - ``desc``, if ``autosum is None`` or ``param`` is not a class - attribute, or it will be a summary of the class attribute's - docstring. - - Notes - ----- - This does not have the autosummary functionality to display a method's - signature, and hence is not used to format methods. It may be - complicated to incorporate autosummary's signature mangling, as it - relies on Sphinx's plugin mechanism. - """ - param = param.strip() - display_param = ('**%s**' if self.use_blockquotes else '%s') % param - - if not fake_autosummary: - return display_param, desc - - param_obj = getattr(self._obj, param, None) - if not (callable(param_obj) - or isinstance(param_obj, property) - or inspect.isgetsetdescriptor(param_obj)): - param_obj = None - obj_doc = pydoc.getdoc(param_obj) - - if not (param_obj and obj_doc): - return display_param, desc - - prefix = getattr(self, '_name', '') - if prefix: - autosum_prefix = '~%s.' % prefix - link_prefix = '%s.' % prefix - else: - autosum_prefix = '' - link_prefix = '' - - # Referenced object has a docstring - display_param = ':obj:`%s <%s%s>`' % (param, - link_prefix, - param) - if obj_doc: - # Overwrite desc. Take summary logic of autosummary - desc = re.split('\n\s*\n', obj_doc.strip(), 1)[0] - # XXX: Should this have DOTALL? - # It does not in autosummary - m = re.search(r"^([A-Z].*?\.)(?:\s|$)", - ' '.join(desc.split())) - if m: - desc = m.group(1).strip() - else: - desc = desc.partition('\n')[0] - desc = desc.split('\n') - return display_param, desc - - def _str_param_list(self, name, fake_autosummary=False): - """Generate RST for a listing of parameters or similar - - Parameter names are displayed as bold text, and descriptions - are in blockquotes. Descriptions may therefore contain block - markup as well. - - Parameters - ---------- - name : str - Section name (e.g. Parameters) - fake_autosummary : bool - When True, the parameter names may correspond to attributes of the - object beign documented, usually ``property`` instances on a class. - In this case, names will be linked to fuller descriptions. - - Returns - ------- - rst : list of str - """ - out = [] - if self[name]: - out += self._str_field_list(name) - out += [''] - for param, param_type, desc in self[name]: - display_param, desc = self._process_param(param, desc, - fake_autosummary) - - if param_type: - out += self._str_indent(['%s : %s' % (display_param, - param_type)]) - else: - out += self._str_indent([display_param]) - if desc and self.use_blockquotes: - out += [''] - elif not desc: - # empty definition - desc = ['..'] - 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() - - # Check if the referenced member can have a docstring or not - param_obj = getattr(self._obj, param, None) - if not (callable(param_obj) - or isinstance(param_obj, property) - or inspect.isdatadescriptor(param_obj)): - param_obj = None - - if param_obj and pydoc.getdoc(param_obj): - # Referenced object has a docstring - autosum += [" %s%s" % (prefix, param)] - else: - others.append((param, param_type, desc)) - - if autosum: - out += ['.. autosummary::'] - if self.class_members_toctree: - out += [' :toctree:'] - out += [''] + autosum - - if others: - maxlen_0 = max(3, max([len(x[0]) + 4 for x in others])) - hdr = sixu("=") * maxlen_0 + sixu(" ") + sixu("=") * 10 - fmt = sixu('%%%ds %%s ') % (maxlen_0,) - out += ['', '', hdr] - for param, param_type, desc in others: - desc = sixu(" ").join(x.strip() for x in desc).strip() - if param_type: - desc = "(%s) %s" % (param_type, desc) - out += [fmt % ("**" + param.strip() + "**", desc)] - out += [hdr] - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - content = textwrap.dedent("\n".join(self[name])).split("\n") - out += content - out += [''] - return out - - def _str_see_also(self, func_role): - out = [] - if self['See Also']: - see_also = super(SphinxDocString, self)._str_see_also(func_role) - out = ['.. seealso::', ''] - out += self._str_indent(see_also[2:]) - return out - - def _str_warnings(self): - out = [] - if self['Warnings']: - out = ['.. warning::', ''] - out += self._str_indent(self['Warnings']) - out += [''] - return out - - def _str_index(self): - idx = self['index'] - out = [] - if len(idx) == 0: - return out - - out += ['.. index:: %s' % idx.get('default', '')] - for section, references in idx.items(): - if section == 'default': - continue - elif section == 'refguide': - out += [' single: %s' % (', '.join(references))] - else: - out += [' %s: %s' % (section, ','.join(references))] - out += [''] - return out - - def _str_references(self): - out = [] - if self['References']: - out += self._str_header('References') - if isinstance(self['References'], str): - self['References'] = [self['References']] - out.extend(self['References']) - 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 re.search(IMPORT_MATPLOTLIB_RE, 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"): - ns = { - 'signature': self._str_signature(), - 'index': self._str_index(), - 'summary': self._str_summary(), - 'extended_summary': self._str_extended_summary(), - 'parameters': self._str_param_list('Parameters'), - 'returns': self._str_returns('Returns'), - 'yields': self._str_returns('Yields'), - 'other_parameters': self._str_param_list('Other Parameters'), - 'raises': self._str_param_list('Raises'), - 'warns': self._str_param_list('Warns'), - 'warnings': self._str_warnings(), - 'see_also': self._str_see_also(func_role), - 'notes': self._str_section('Notes'), - 'references': self._str_references(), - 'examples': self._str_examples(), - 'attributes': - self._str_param_list('Attributes', fake_autosummary=True) - if self.attributes_as_param_list - else self._str_member_list('Attributes'), - 'methods': self._str_member_list('Methods'), - } - ns = dict((k, '\n'.join(v)) for k, v in ns.items()) - - rendered = self.template.render(**ns) - return '\n'.join(self._str_indent(rendered.split('\n'), indent)) - - -class SphinxFunctionDoc(SphinxDocString, FunctionDoc): - def __init__(self, obj, doc=None, config={}): - self.load_config(config) - FunctionDoc.__init__(self, obj, doc=doc, config=config) - - -class SphinxClassDoc(SphinxDocString, ClassDoc): - def __init__(self, obj, doc=None, func_doc=None, config={}): - self.load_config(config) - ClassDoc.__init__(self, obj, doc=doc, func_doc=None, config=config) - - -class SphinxObjDoc(SphinxDocString): - def __init__(self, obj, doc=None, config={}): - self._f = obj - self.load_config(config) - SphinxDocString.__init__(self, doc, config=config) - - -def get_doc_object(obj, what=None, doc=None, config={}, builder=None): - if what is None: - if inspect.isclass(obj): - what = 'class' - elif inspect.ismodule(obj): - what = 'module' - elif isinstance(obj, collections.Callable): - what = 'function' - else: - what = 'object' - - template_dirs = [os.path.join(os.path.dirname(__file__), 'templates')] - if builder is not None: - template_loader = BuiltinTemplateLoader() - template_loader.init(builder, dirs=template_dirs) - else: - template_loader = FileSystemLoader(template_dirs) - template_env = SandboxedEnvironment(loader=template_loader) - config['template'] = template_env.get_template('numpydoc_docstring.rst') - - if what == 'class': - return SphinxClassDoc(obj, func_doc=SphinxFunctionDoc, doc=doc, - config=config) - elif what in ('function', 'method'): - return SphinxFunctionDoc(obj, doc=doc, config=config) - else: - if doc is None: - doc = pydoc.getdoc(obj) - return SphinxObjDoc(obj, doc, config=config) diff --git a/doc/sphinxext/numpydoc/numpydoc.py b/doc/sphinxext/numpydoc/numpydoc.py deleted file mode 100644 index dc20b3f828eb2..0000000000000 --- a/doc/sphinxext/numpydoc/numpydoc.py +++ /dev/null @@ -1,288 +0,0 @@ -""" -======== -numpydoc -======== - -Sphinx extension that handles docstrings in the Numpy standard format. [1] - -It will: - -- Convert Parameters etc. sections to field lists. -- Convert See Also section to a See also entry. -- Renumber references. -- Extract the signature from the docstring, if it can't be determined - otherwise. - -.. [1] https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt - -""" -from __future__ import division, absolute_import, print_function - -import sys -import re -import pydoc -import sphinx -import inspect -import collections - -if sphinx.__version__ < '1.0.1': - raise RuntimeError("Sphinx 1.0.1 or newer is required") - -from .docscrape_sphinx import get_doc_object, SphinxDocString -from . import __version__ - -if sys.version_info[0] >= 3: - sixu = lambda s: s -else: - sixu = lambda s: unicode(s, 'unicode_escape') - - -def rename_references(app, what, name, obj, options, lines, - reference_offset=[0]): - # replace reference numbers so that there are no duplicates - references = set() - for line in lines: - line = line.strip() - m = re.match(sixu('^.. \\[(%s)\\]') % app.config.numpydoc_citation_re, - line, re.I) - if m: - references.add(m.group(1)) - - if references: - for r in references: - if r.isdigit(): - new_r = sixu("R%d") % (reference_offset[0] + int(r)) - else: - new_r = sixu("%s%d") % (r, reference_offset[0]) - - for i, line in enumerate(lines): - lines[i] = lines[i].replace(sixu('[%s]_') % r, - sixu('[%s]_') % new_r) - lines[i] = lines[i].replace(sixu('.. [%s]') % r, - sixu('.. [%s]') % new_r) - - reference_offset[0] += len(references) - - -DEDUPLICATION_TAG = ' !! processed by numpydoc !!' - - -def mangle_docstrings(app, what, name, obj, options, lines): - if DEDUPLICATION_TAG in lines: - return - - cfg = {'use_plots': app.config.numpydoc_use_plots, - 'use_blockquotes': app.config.numpydoc_use_blockquotes, - 'show_class_members': app.config.numpydoc_show_class_members, - 'show_inherited_class_members': - app.config.numpydoc_show_inherited_class_members, - 'class_members_toctree': app.config.numpydoc_class_members_toctree, - 'attributes_as_param_list': - app.config.numpydoc_attributes_as_param_list} - - u_NL = sixu('\n') - if what == 'module': - # Strip top title - pattern = '^\\s*[#*=]{4,}\\n[a-z0-9 -]+\\n[#*=]{4,}\\s*' - title_re = re.compile(sixu(pattern), re.I | re.S) - lines[:] = title_re.sub(sixu(''), u_NL.join(lines)).split(u_NL) - else: - doc = get_doc_object(obj, what, u_NL.join(lines), config=cfg, - builder=app.builder) - if sys.version_info[0] >= 3: - doc = str(doc) - else: - doc = unicode(doc) - lines[:] = doc.split(u_NL) - - if (app.config.numpydoc_edit_link and hasattr(obj, '__name__') and - obj.__name__): - if hasattr(obj, '__module__'): - v = dict(full_name=sixu("%s.%s") % (obj.__module__, obj.__name__)) - else: - v = dict(full_name=obj.__name__) - lines += [sixu(''), sixu('.. htmlonly::'), sixu('')] - lines += [sixu(' %s') % x for x in - (app.config.numpydoc_edit_link % v).split("\n")] - - # call function to replace reference numbers so that there are no - # duplicates - rename_references(app, what, name, obj, options, lines) - - lines += ['..', DEDUPLICATION_TAG] - - -def mangle_signature(app, what, name, obj, options, sig, retann): - # Do not try to inspect classes that don't define `__init__` - if (inspect.isclass(obj) and - (not hasattr(obj, '__init__') or - 'initializes x; see ' in pydoc.getdoc(obj.__init__))): - return '', '' - - if not (isinstance(obj, collections.Callable) or - hasattr(obj, '__argspec_is_invalid_')): - return - - if not hasattr(obj, '__doc__'): - return - doc = SphinxDocString(pydoc.getdoc(obj)) - sig = doc['Signature'] or getattr(obj, '__text_signature__', None) - if sig: - sig = re.sub(sixu("^[^(]*"), sixu(""), sig) - return sig, sixu('') - - -def setup(app, get_doc_object_=get_doc_object): - if not hasattr(app, 'add_config_value'): - return # probably called by nose, better bail out - - global get_doc_object - get_doc_object = get_doc_object_ - - app.connect('autodoc-process-docstring', mangle_docstrings) - app.connect('autodoc-process-signature', mangle_signature) - app.add_config_value('numpydoc_edit_link', None, False) - app.add_config_value('numpydoc_use_plots', None, False) - app.add_config_value('numpydoc_use_blockquotes', None, False) - app.add_config_value('numpydoc_show_class_members', True, True) - app.add_config_value('numpydoc_show_inherited_class_members', True, True) - app.add_config_value('numpydoc_class_members_toctree', True, True) - app.add_config_value('numpydoc_citation_re', '[a-z0-9_.-]+', True) - app.add_config_value('numpydoc_attributes_as_param_list', True, True) - - # Extra mangling domains - app.add_domain(NumpyPythonDomain) - app.add_domain(NumpyCDomain) - - app.setup_extension('sphinx.ext.autosummary') - - metadata = {'version': __version__, - 'parallel_read_safe': True} - return metadata - -# ------------------------------------------------------------------------------ -# Docstring-mangling domains -# ------------------------------------------------------------------------------ - -from docutils.statemachine import ViewList -from sphinx.domains.c import CDomain -from sphinx.domains.python import PythonDomain - - -class ManglingDomainBase(object): - directive_mangling_map = {} - - def __init__(self, *a, **kw): - super(ManglingDomainBase, self).__init__(*a, **kw) - self.wrap_mangling_directives() - - def wrap_mangling_directives(self): - for name, objtype in list(self.directive_mangling_map.items()): - self.directives[name] = wrap_mangling_directive( - self.directives[name], objtype) - - -class NumpyPythonDomain(ManglingDomainBase, PythonDomain): - name = 'np' - directive_mangling_map = { - 'function': 'function', - 'class': 'class', - 'exception': 'class', - 'method': 'function', - 'classmethod': 'function', - 'staticmethod': 'function', - 'attribute': 'attribute', - } - indices = [] - - -class NumpyCDomain(ManglingDomainBase, CDomain): - name = 'np-c' - directive_mangling_map = { - 'function': 'function', - 'member': 'attribute', - 'macro': 'function', - 'type': 'class', - 'var': 'object', - } - - -def match_items(lines, content_old): - """Create items for mangled lines. - - This function tries to match the lines in ``lines`` with the items (source - file references and line numbers) in ``content_old``. The - ``mangle_docstrings`` function changes the actual docstrings, but doesn't - keep track of where each line came from. The manging does many operations - on the original lines, which are hard to track afterwards. - - Many of the line changes come from deleting or inserting blank lines. This - function tries to match lines by ignoring blank lines. All other changes - (such as inserting figures or changes in the references) are completely - ignored, so the generated line numbers will be off if ``mangle_docstrings`` - does anything non-trivial. - - This is a best-effort function and the real fix would be to make - ``mangle_docstrings`` actually keep track of the ``items`` together with - the ``lines``. - - Examples - -------- - >>> lines = ['', 'A', '', 'B', ' ', '', 'C', 'D'] - >>> lines_old = ['a', '', '', 'b', '', 'c'] - >>> items_old = [('file1.py', 0), ('file1.py', 1), ('file1.py', 2), - ... ('file2.py', 0), ('file2.py', 1), ('file2.py', 2)] - >>> content_old = ViewList(lines_old, items=items_old) - >>> match_items(lines, content_old) # doctest: +NORMALIZE_WHITESPACE - [('file1.py', 0), ('file1.py', 0), ('file2.py', 0), ('file2.py', 0), - ('file2.py', 2), ('file2.py', 2), ('file2.py', 2), ('file2.py', 2)] - >>> # first 2 ``lines`` are matched to 'a', second 2 to 'b', rest to 'c' - >>> # actual content is completely ignored. - - Notes - ----- - The algorithm tries to match any line in ``lines`` with one in - ``lines_old``. It skips over all empty lines in ``lines_old`` and assigns - this line number to all lines in ``lines``, unless a non-empty line is - found in ``lines`` in which case it goes to the next line in ``lines_old``. - - """ - items_new = [] - lines_old = content_old.data - items_old = content_old.items - j = 0 - for i, line in enumerate(lines): - # go to next non-empty line in old: - # line.strip() checks whether the string is all whitespace - while j < len(lines_old) - 1 and not lines_old[j].strip(): - j += 1 - items_new.append(items_old[j]) - if line.strip() and j < len(lines_old) - 1: - j += 1 - assert(len(items_new) == len(lines)) - return items_new - - -def wrap_mangling_directive(base_directive, objtype): - class directive(base_directive): - def run(self): - env = self.state.document.settings.env - - name = None - if self.arguments: - m = re.match(r'^(.*\s+)?(.*?)(\(.*)?', self.arguments[0]) - name = m.group(2).strip() - - if not name: - name = self.arguments[0] - - lines = list(self.content) - mangle_docstrings(env.app, objtype, name, None, None, lines) - if self.content: - items = match_items(lines, self.content) - self.content = ViewList(lines, items=items, - parent=self.content.parent) - - return base_directive.run(self) - - return directive diff --git a/doc/sphinxext/numpydoc/templates/numpydoc_docstring.rst b/doc/sphinxext/numpydoc/templates/numpydoc_docstring.rst deleted file mode 100644 index 1900db53cee47..0000000000000 --- a/doc/sphinxext/numpydoc/templates/numpydoc_docstring.rst +++ /dev/null @@ -1,16 +0,0 @@ -{{index}} -{{summary}} -{{extended_summary}} -{{parameters}} -{{returns}} -{{yields}} -{{other_parameters}} -{{raises}} -{{warns}} -{{warnings}} -{{see_also}} -{{notes}} -{{references}} -{{examples}} -{{attributes}} -{{methods}} diff --git a/doc/sphinxext/numpydoc/tests/test_docscrape.py b/doc/sphinxext/numpydoc/tests/test_docscrape.py deleted file mode 100644 index 2fb4eb5ab277e..0000000000000 --- a/doc/sphinxext/numpydoc/tests/test_docscrape.py +++ /dev/null @@ -1,1204 +0,0 @@ -# -*- encoding:utf-8 -*- -from __future__ import division, absolute_import, print_function - -import re -import sys -import textwrap -import warnings - -import jinja2 - -from numpydoc.docscrape import ( - NumpyDocString, - FunctionDoc, - ClassDoc, - ParseError -) -from numpydoc.docscrape_sphinx import (SphinxDocString, SphinxClassDoc, - SphinxFunctionDoc) -from nose.tools import (assert_equal, assert_raises, assert_list_equal, - assert_true) - -assert_list_equal.__self__.maxDiff = None - -if sys.version_info[0] >= 3: - sixu = lambda s: s -else: - sixu = lambda s: unicode(s, 'unicode_escape') - - -doc_txt = '''\ - numpy.multivariate_normal(mean, cov, shape=None, spam=None) - - Draw values from a multivariate normal distribution with specified - mean and covariance. - - The multivariate normal or Gaussian distribution is a generalisation - of the one-dimensional normal distribution to higher dimensions. - - Parameters - ---------- - mean : (N,) ndarray - Mean of the N-dimensional distribution. - - .. math:: - - (1+2+3)/3 - - cov : (N, N) ndarray - Covariance matrix of the distribution. - shape : tuple of ints - Given a shape of, for example, (m,n,k), m*n*k samples are - generated, and packed in an m-by-n-by-k arrangement. Because - each sample is N-dimensional, the output shape is (m,n,k,N). - - Returns - ------- - out : ndarray - The drawn samples, arranged according to `shape`. If the - shape given is (m,n,...), then the shape of `out` is - (m,n,...,N). - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. - list of str - This is not a real return value. It exists to test - anonymous return values. - no_description - - Other Parameters - ---------------- - spam : parrot - A parrot off its mortal coil. - - Raises - ------ - RuntimeError - Some error - - Warns - ----- - RuntimeWarning - Some warning - - Warnings - -------- - Certain warnings apply. - - Notes - ----- - Instead of specifying the full covariance matrix, popular - approximations include: - - - Spherical covariance (`cov` is a multiple of the identity matrix) - - Diagonal covariance (`cov` has non-negative elements only on the diagonal) - - This geometrical property can be seen in two dimensions by plotting - generated data-points: - - >>> mean = [0,0] - >>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis - - >>> x,y = multivariate_normal(mean,cov,5000).T - >>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show() - - Note that the covariance matrix must be symmetric and non-negative - definite. - - References - ---------- - .. [1] A. Papoulis, "Probability, Random Variables, and Stochastic - Processes," 3rd ed., McGraw-Hill Companies, 1991 - .. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification," - 2nd ed., Wiley, 2001. - - See Also - -------- - some, other, funcs - otherfunc : relationship - - Examples - -------- - >>> mean = (1,2) - >>> cov = [[1,0],[1,0]] - >>> x = multivariate_normal(mean,cov,(3,3)) - >>> print x.shape - (3, 3, 2) - - The following is probably true, given that 0.6 is roughly twice the - standard deviation: - - >>> print list( (x[0,0,:] - mean) < 0.6 ) - [True, True] - - .. index:: random - :refguide: random;distributions, random;gauss - - ''' -doc = NumpyDocString(doc_txt) - -doc_yields_txt = """ -Test generator - -Yields ------- -a : int - The number of apples. -b : int - The number of bananas. -int - The number of unknowns. -""" -doc_yields = NumpyDocString(doc_yields_txt) - - -def test_signature(): - assert doc['Signature'].startswith('numpy.multivariate_normal(') - assert doc['Signature'].endswith('spam=None)') - - -def test_summary(): - assert doc['Summary'][0].startswith('Draw values') - assert doc['Summary'][-1].endswith('covariance.') - - -def test_extended_summary(): - assert doc['Extended Summary'][0].startswith('The multivariate normal') - - -def test_parameters(): - assert_equal(len(doc['Parameters']), 3) - assert_equal([n for n,_,_ in doc['Parameters']], ['mean','cov','shape']) - - arg, arg_type, desc = doc['Parameters'][1] - assert_equal(arg_type, '(N, N) ndarray') - assert desc[0].startswith('Covariance matrix') - assert doc['Parameters'][0][-1][-1] == ' (1+2+3)/3' - - -def test_other_parameters(): - assert_equal(len(doc['Other Parameters']), 1) - assert_equal([n for n,_,_ in doc['Other Parameters']], ['spam']) - arg, arg_type, desc = doc['Other Parameters'][0] - assert_equal(arg_type, 'parrot') - assert desc[0].startswith('A parrot off its mortal coil') - - -def test_returns(): - assert_equal(len(doc['Returns']), 3) - arg, arg_type, desc = doc['Returns'][0] - assert_equal(arg, 'out') - assert_equal(arg_type, 'ndarray') - assert desc[0].startswith('The drawn samples') - assert desc[-1].endswith('distribution.') - - arg, arg_type, desc = doc['Returns'][1] - assert_equal(arg, 'list of str') - assert_equal(arg_type, '') - assert desc[0].startswith('This is not a real') - assert desc[-1].endswith('anonymous return values.') - - arg, arg_type, desc = doc['Returns'][2] - assert_equal(arg, 'no_description') - assert_equal(arg_type, '') - assert not ''.join(desc).strip() - - -def test_yields(): - section = doc_yields['Yields'] - assert_equal(len(section), 3) - truth = [('a', 'int', 'apples.'), - ('b', 'int', 'bananas.'), - ('int', '', 'unknowns.')] - for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): - assert_equal(arg, arg_) - assert_equal(arg_type, arg_type_) - assert desc[0].startswith('The number of') - assert desc[0].endswith(end) - - -def test_returnyield(): - doc_text = """ -Test having returns and yields. - -Returns -------- -int - The number of apples. - -Yields ------- -a : int - The number of apples. -b : int - The number of bananas. - -""" - assert_raises(ValueError, NumpyDocString, doc_text) - - -def test_section_twice(): - doc_text = """ -Test having a section Notes twice - -Notes ------ -See the next note for more information - -Notes ------ -That should break... -""" - assert_raises(ValueError, NumpyDocString, doc_text) - - # if we have a numpydoc object, we know where the error came from - class Dummy(object): - """ - Dummy class. - - Notes - ----- - First note. - - Notes - ----- - Second note. - - """ - def spam(self, a, b): - """Spam\n\nSpam spam.""" - pass - - def ham(self, c, d): - """Cheese\n\nNo cheese.""" - pass - - def dummy_func(arg): - """ - Dummy function. - - Notes - ----- - First note. - - Notes - ----- - Second note. - """ - - try: - SphinxClassDoc(Dummy) - except ValueError as e: - # python 3 version or python 2 version - assert_true("test_section_twice..Dummy" in str(e) - or 'test_docscrape.Dummy' in str(e)) - - try: - SphinxFunctionDoc(dummy_func) - except ValueError as e: - # python 3 version or python 2 version - assert_true("test_section_twice..dummy_func" in str(e) - or 'function dummy_func' in str(e)) - - -def test_notes(): - assert doc['Notes'][0].startswith('Instead') - assert doc['Notes'][-1].endswith('definite.') - assert_equal(len(doc['Notes']), 17) - - -def test_references(): - assert doc['References'][0].startswith('..') - assert doc['References'][-1].endswith('2001.') - - -def test_examples(): - assert doc['Examples'][0].startswith('>>>') - assert doc['Examples'][-1].endswith('True]') - - -def test_index(): - assert_equal(doc['index']['default'], 'random') - assert_equal(len(doc['index']), 2) - assert_equal(len(doc['index']['refguide']), 2) - - -def _strip_blank_lines(s): - "Remove leading, trailing and multiple blank lines" - s = re.sub(r'^\s*\n', '', s) - s = re.sub(r'\n\s*$', '', s) - s = re.sub(r'\n\s*\n', r'\n\n', s) - return s - - -def line_by_line_compare(a, b): - a = textwrap.dedent(a) - b = textwrap.dedent(b) - a = [l.rstrip() for l in _strip_blank_lines(a).split('\n')] - b = [l.rstrip() for l in _strip_blank_lines(b).split('\n')] - assert_list_equal(a, b) - - -def test_str(): - # doc_txt has the order of Notes and See Also sections flipped. - # This should be handled automatically, and so, one thing this test does - # is to make sure that See Also precedes Notes in the output. - line_by_line_compare(str(doc), -"""numpy.multivariate_normal(mean, cov, shape=None, spam=None) - -Draw values from a multivariate normal distribution with specified -mean and covariance. - -The multivariate normal or Gaussian distribution is a generalisation -of the one-dimensional normal distribution to higher dimensions. - -Parameters ----------- -mean : (N,) ndarray - Mean of the N-dimensional distribution. - - .. math:: - - (1+2+3)/3 -cov : (N, N) ndarray - Covariance matrix of the distribution. -shape : tuple of ints - Given a shape of, for example, (m,n,k), m*n*k samples are - generated, and packed in an m-by-n-by-k arrangement. Because - each sample is N-dimensional, the output shape is (m,n,k,N). - -Returns -------- -out : ndarray - The drawn samples, arranged according to `shape`. If the - shape given is (m,n,...), then the shape of `out` is - (m,n,...,N). - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. -list of str - This is not a real return value. It exists to test - anonymous return values. -no_description - -Other Parameters ----------------- -spam : parrot - A parrot off its mortal coil. - -Raises ------- -RuntimeError - Some error - -Warns ------ -RuntimeWarning - Some warning - -Warnings --------- -Certain warnings apply. - -See Also --------- - -`some`_, `other`_, `funcs`_ - -`otherfunc`_ - relationship - -Notes ------ -Instead of specifying the full covariance matrix, popular -approximations include: - - - Spherical covariance (`cov` is a multiple of the identity matrix) - - Diagonal covariance (`cov` has non-negative elements only on the diagonal) - -This geometrical property can be seen in two dimensions by plotting -generated data-points: - ->>> mean = [0,0] ->>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis - ->>> x,y = multivariate_normal(mean,cov,5000).T ->>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show() - -Note that the covariance matrix must be symmetric and non-negative -definite. - -References ----------- -.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic - Processes," 3rd ed., McGraw-Hill Companies, 1991 -.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification," - 2nd ed., Wiley, 2001. - -Examples --------- ->>> mean = (1,2) ->>> cov = [[1,0],[1,0]] ->>> x = multivariate_normal(mean,cov,(3,3)) ->>> print x.shape -(3, 3, 2) - -The following is probably true, given that 0.6 is roughly twice the -standard deviation: - ->>> print list( (x[0,0,:] - mean) < 0.6 ) -[True, True] - -.. index:: random - :refguide: random;distributions, random;gauss""") - - -def test_yield_str(): - line_by_line_compare(str(doc_yields), -"""Test generator - -Yields ------- -a : int - The number of apples. -b : int - The number of bananas. -int - The number of unknowns. - -.. index:: """) - - -def test_sphinx_str(): - sphinx_doc = SphinxDocString(doc_txt) - line_by_line_compare(str(sphinx_doc), -""" -.. index:: random - single: random;distributions, random;gauss - -Draw values from a multivariate normal distribution with specified -mean and covariance. - -The multivariate normal or Gaussian distribution is a generalisation -of the one-dimensional normal distribution to higher dimensions. - -:Parameters: - - mean : (N,) ndarray - Mean of the N-dimensional distribution. - - .. math:: - - (1+2+3)/3 - - cov : (N, N) ndarray - Covariance matrix of the distribution. - - shape : tuple of ints - Given a shape of, for example, (m,n,k), m*n*k samples are - generated, and packed in an m-by-n-by-k arrangement. Because - each sample is N-dimensional, the output shape is (m,n,k,N). - -:Returns: - - out : ndarray - The drawn samples, arranged according to `shape`. If the - shape given is (m,n,...), then the shape of `out` is - (m,n,...,N). - - In other words, each entry ``out[i,j,...,:]`` is an N-dimensional - value drawn from the distribution. - - list of str - This is not a real return value. It exists to test - anonymous return values. - - no_description - .. - -:Other Parameters: - - spam : parrot - A parrot off its mortal coil. - -:Raises: - - RuntimeError - Some error - -:Warns: - - RuntimeWarning - Some warning - -.. warning:: - - Certain warnings apply. - -.. seealso:: - - :obj:`some`, :obj:`other`, :obj:`funcs` - - :obj:`otherfunc` - relationship - -.. rubric:: Notes - -Instead of specifying the full covariance matrix, popular -approximations include: - - - Spherical covariance (`cov` is a multiple of the identity matrix) - - Diagonal covariance (`cov` has non-negative elements only on the diagonal) - -This geometrical property can be seen in two dimensions by plotting -generated data-points: - ->>> mean = [0,0] ->>> cov = [[1,0],[0,100]] # diagonal covariance, points lie on x or y-axis - ->>> x,y = multivariate_normal(mean,cov,5000).T ->>> plt.plot(x,y,'x'); plt.axis('equal'); plt.show() - -Note that the covariance matrix must be symmetric and non-negative -definite. - -.. rubric:: References - -.. [1] A. Papoulis, "Probability, Random Variables, and Stochastic - Processes," 3rd ed., McGraw-Hill Companies, 1991 -.. [2] R.O. Duda, P.E. Hart, and D.G. Stork, "Pattern Classification," - 2nd ed., Wiley, 2001. - -.. only:: latex - - [1]_, [2]_ - -.. rubric:: Examples - ->>> mean = (1,2) ->>> cov = [[1,0],[1,0]] ->>> x = multivariate_normal(mean,cov,(3,3)) ->>> print x.shape -(3, 3, 2) - -The following is probably true, given that 0.6 is roughly twice the -standard deviation: - ->>> print list( (x[0,0,:] - mean) < 0.6 ) -[True, True] -""") - - -def test_sphinx_yields_str(): - sphinx_doc = SphinxDocString(doc_yields_txt) - line_by_line_compare(str(sphinx_doc), -"""Test generator - -:Yields: - - a : int - The number of apples. - - b : int - The number of bananas. - - int - The number of unknowns. -""") - - -doc2 = NumpyDocString(""" - Returns array of indices of the maximum values of along the given axis. - - Parameters - ---------- - a : {array_like} - Array to look in. - axis : {None, integer} - If None, the index is into the flattened array, otherwise along - the specified axis""") - - -def test_parameters_without_extended_description(): - assert_equal(len(doc2['Parameters']), 2) - - -doc3 = NumpyDocString(""" - my_signature(*params, **kwds) - - Return this and that. - """) - - -def test_escape_stars(): - signature = str(doc3).split('\n')[0] - assert_equal(signature, 'my_signature(\*params, \*\*kwds)') - - def my_func(a, b, **kwargs): - pass - - fdoc = FunctionDoc(func=my_func) - assert_equal(fdoc['Signature'], 'my_func(a, b, \*\*kwargs)') - - -doc4 = NumpyDocString( - """a.conj() - - Return an array with all complex-valued elements conjugated.""") - - -def test_empty_extended_summary(): - assert_equal(doc4['Extended Summary'], []) - - -doc5 = NumpyDocString( - """ - a.something() - - Raises - ------ - LinAlgException - If array is singular. - - Warns - ----- - SomeWarning - If needed - """) - - -def test_raises(): - assert_equal(len(doc5['Raises']), 1) - name,_,desc = doc5['Raises'][0] - assert_equal(name,'LinAlgException') - assert_equal(desc,['If array is singular.']) - - -def test_warns(): - assert_equal(len(doc5['Warns']), 1) - name,_,desc = doc5['Warns'][0] - assert_equal(name,'SomeWarning') - assert_equal(desc,['If needed']) - - -def test_see_also(): - doc6 = NumpyDocString( - """ - z(x,theta) - - See Also - -------- - func_a, func_b, func_c - func_d : some equivalent func - foo.func_e : some other func over - multiple lines - func_f, func_g, :meth:`func_h`, func_j, - func_k - :obj:`baz.obj_q` - :obj:`~baz.obj_r` - :class:`class_j`: fubar - foobar - """) - - assert len(doc6['See Also']) == 13 - for func, desc, role in doc6['See Also']: - if func in ('func_a', 'func_b', 'func_c', 'func_f', - 'func_g', 'func_h', 'func_j', 'func_k', 'baz.obj_q', - '~baz.obj_r'): - assert(not desc) - else: - assert(desc) - - if func == 'func_h': - assert role == 'meth' - elif func == 'baz.obj_q' or func == '~baz.obj_r': - assert role == 'obj' - elif func == 'class_j': - assert role == 'class' - else: - assert role is None - - if func == 'func_d': - assert desc == ['some equivalent func'] - elif func == 'foo.func_e': - assert desc == ['some other func over', 'multiple lines'] - elif func == 'class_j': - assert desc == ['fubar', 'foobar'] - - -def test_see_also_parse_error(): - text = ( - """ - z(x,theta) - - See Also - -------- - :func:`~foo` - """) - with assert_raises(ParseError) as err: - NumpyDocString(text) - assert_equal( - str(r":func:`~foo` is not a item name in '\n z(x,theta)\n\n See Also\n --------\n :func:`~foo`\n '"), - str(err.exception) - ) - -def test_see_also_print(): - class Dummy(object): - """ - See Also - -------- - func_a, func_b - func_c : some relationship - goes here - func_d - """ - pass - - obj = Dummy() - s = str(FunctionDoc(obj, role='func')) - assert(':func:`func_a`, :func:`func_b`' in s) - assert(' some relationship' in s) - assert(':func:`func_d`' in s) - - -def test_unknown_section(): - doc_text = """ -Test having an unknown section - -Mope ----- -This should be ignored and warned about -""" - - class BadSection(object): - """Class with bad section. - - Nope - ---- - This class has a nope section. - """ - pass - - with warnings.catch_warnings(record=True) as w: - NumpyDocString(doc_text) - assert len(w) == 1 - assert "Unknown section Mope" == str(w[0].message) - - with warnings.catch_warnings(record=True) as w: - SphinxClassDoc(BadSection) - assert len(w) == 1 - assert_true('test_docscrape.test_unknown_section..BadSection' - in str(w[0].message) - or 'test_docscrape.BadSection' in str(w[0].message)) - - -doc7 = NumpyDocString(""" - - Doc starts on second line. - - """) - - -def test_empty_first_line(): - assert doc7['Summary'][0].startswith('Doc starts') - - -def test_no_summary(): - str(SphinxDocString(""" - Parameters - ----------""")) - - -def test_unicode(): - doc = SphinxDocString(""" - öäöäöäöäöåååå - - öäöäöäööäååå - - Parameters - ---------- - ååå : äää - ööö - - Returns - ------- - ååå : ööö - äää - - """) - assert isinstance(doc['Summary'][0], str) - assert doc['Summary'][0] == 'öäöäöäöäöåååå' - - -def test_plot_examples(): - cfg = dict(use_plots=True) - - doc = SphinxDocString(""" - Examples - -------- - >>> import matplotlib.pyplot as plt - >>> plt.plot([1,2,3],[4,5,6]) - >>> plt.show() - """, config=cfg) - assert 'plot::' in str(doc), str(doc) - - doc = SphinxDocString(""" - Examples - -------- - >>> from matplotlib import pyplot as plt - >>> plt.plot([1,2,3],[4,5,6]) - >>> plt.show() - """, config=cfg) - assert 'plot::' in str(doc), str(doc) - - doc = SphinxDocString(""" - Examples - -------- - .. plot:: - - import matplotlib.pyplot as plt - plt.plot([1,2,3],[4,5,6]) - plt.show() - """, config=cfg) - assert str(doc).count('plot::') == 1, str(doc) - - -def test_use_blockquotes(): - cfg = dict(use_blockquotes=True) - doc = SphinxDocString(""" - Parameters - ---------- - abc : def - ghi - jkl - mno - - Returns - ------- - ABC : DEF - GHI - JKL - MNO - """, config=cfg) - line_by_line_compare(str(doc), ''' - :Parameters: - - **abc** : def - - ghi - - **jkl** - - mno - - :Returns: - - **ABC** : DEF - - GHI - - **JKL** - - MNO - ''') - - -def test_class_members(): - - class Dummy(object): - """ - Dummy class. - - """ - def spam(self, a, b): - """Spam\n\nSpam spam.""" - pass - def ham(self, c, d): - """Cheese\n\nNo cheese.""" - pass - @property - def spammity(self): - """Spammity index""" - return 0.95 - - class Ignorable(object): - """local class, to be ignored""" - pass - - for cls in (ClassDoc, SphinxClassDoc): - doc = cls(Dummy, config=dict(show_class_members=False)) - assert 'Methods' not in str(doc), (cls, str(doc)) - assert 'spam' not in str(doc), (cls, str(doc)) - assert 'ham' not in str(doc), (cls, str(doc)) - assert 'spammity' not in str(doc), (cls, str(doc)) - assert 'Spammity index' not in str(doc), (cls, str(doc)) - - doc = cls(Dummy, config=dict(show_class_members=True)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'spammity' in str(doc), (cls, str(doc)) - - if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) - else: - assert 'Spammity index' in str(doc), str(doc) - - class SubDummy(Dummy): - """ - Subclass of Dummy class. - - """ - def ham(self, c, d): - """Cheese\n\nNo cheese.\nOverloaded Dummy.ham""" - pass - - def bar(self, a, b): - """Bar\n\nNo bar""" - pass - - for cls in (ClassDoc, SphinxClassDoc): - doc = cls(SubDummy, config=dict(show_class_members=True, - show_inherited_class_members=False)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' not in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'bar' in str(doc), (cls, str(doc)) - assert 'spammity' not in str(doc), (cls, str(doc)) - - if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) - else: - assert 'Spammity index' not in str(doc), str(doc) - - doc = cls(SubDummy, config=dict(show_class_members=True, - show_inherited_class_members=True)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'bar' in str(doc), (cls, str(doc)) - assert 'spammity' in str(doc), (cls, str(doc)) - - if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) - else: - assert 'Spammity index' in str(doc), str(doc) - - -def test_duplicate_signature(): - # Duplicate function signatures occur e.g. in ufuncs, when the - # automatic mechanism adds one, and a more detailed comes from the - # docstring itself. - - doc = NumpyDocString( - """ - z(x1, x2) - - z(a, theta) - """) - - assert doc['Signature'].strip() == 'z(a, theta)' - - -class_doc_txt = """ - Foo - - Parameters - ---------- - f : callable ``f(t, y, *f_args)`` - Aaa. - jac : callable ``jac(t, y, *jac_args)`` - - Bbb. - - Attributes - ---------- - t : float - Current time. - y : ndarray - Current variable values. - - * hello - * world - an_attribute : float - The docstring is printed instead - no_docstring : str - But a description - no_docstring2 : str - multiline_sentence - midword_period - no_period - - Methods - ------- - a - b - c - - Examples - -------- - For usage examples, see `ode`. -""" - - -def test_class_members_doc(): - doc = ClassDoc(None, class_doc_txt) - line_by_line_compare(str(doc), - """ - Foo - - Parameters - ---------- - f : callable ``f(t, y, *f_args)`` - Aaa. - jac : callable ``jac(t, y, *jac_args)`` - Bbb. - - Examples - -------- - For usage examples, see `ode`. - - Attributes - ---------- - t : float - Current time. - y : ndarray - Current variable values. - - * hello - * world - an_attribute : float - The docstring is printed instead - no_docstring : str - But a description - no_docstring2 : str - multiline_sentence - midword_period - no_period - - Methods - ------- - a - b - c - - .. index:: - - """) - - -def test_class_members_doc_sphinx(): - class Foo: - @property - def an_attribute(self): - """Test attribute""" - return None - - @property - def no_docstring(self): - return None - - @property - def no_docstring2(self): - return None - - @property - def multiline_sentence(self): - """This is a - sentence. It spans multiple lines.""" - return None - - @property - def midword_period(self): - """The sentence for numpy.org.""" - return None - - @property - def no_period(self): - """This does not have a period - so we truncate its summary to the first linebreak - - Apparently. - """ - return None - - doc = SphinxClassDoc(Foo, class_doc_txt) - line_by_line_compare(str(doc), - """ - Foo - - :Parameters: - - f : callable ``f(t, y, *f_args)`` - Aaa. - - jac : callable ``jac(t, y, *jac_args)`` - Bbb. - - .. rubric:: Examples - - For usage examples, see `ode`. - - :Attributes: - - t : float - Current time. - - y : ndarray - Current variable values. - - * hello - * world - - :obj:`an_attribute ` : float - Test attribute - - no_docstring : str - But a description - - no_docstring2 : str - .. - - :obj:`multiline_sentence ` - This is a sentence. - - :obj:`midword_period ` - The sentence for numpy.org. - - :obj:`no_period ` - This does not have a period - - .. rubric:: Methods - - ===== ========== - **a** - **b** - **c** - ===== ========== - - """) - - -def test_templated_sections(): - doc = SphinxClassDoc(None, class_doc_txt, - config={'template': jinja2.Template('{{examples}}\n{{parameters}}')}) - line_by_line_compare(str(doc), - """ - .. rubric:: Examples - - For usage examples, see `ode`. - - :Parameters: - - f : callable ``f(t, y, *f_args)`` - Aaa. - - jac : callable ``jac(t, y, *jac_args)`` - Bbb. - - """) - - -if __name__ == "__main__": - import nose - nose.run() diff --git a/environment.yml b/environment.yml index e31511e5b8afe..a2342d37dd6a4 100644 --- a/environment.yml +++ b/environment.yml @@ -22,6 +22,7 @@ dependencies: - pytest>=4.0 - sphinx - sphinxcontrib-spelling + - numpydoc # optional - beautifulsoup4>=4.2.1 diff --git a/pandas/core/ops.py b/pandas/core/ops.py index 41e3f4581587e..61bf73cbc280f 100644 --- a/pandas/core/ops.py +++ b/pandas/core/ops.py @@ -531,7 +531,7 @@ def _get_op_name(op, special): for missing data in one of the inputs. With reverse version, `{reverse}`. Among flexible wrappers (`add`, `sub`, `mul`, `div`, `mod`, `pow`) to -arithmetic operators: `+`, `-`, `*`, `/`, `//`, `%`, `**. +arithmetic operators: `+`, `-`, `*`, `/`, `//`, `%`, `**`. Parameters ---------- diff --git a/requirements-dev.txt b/requirements-dev.txt index facadf384f770..dfaf280d65f1c 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -13,6 +13,7 @@ moto pytest>=4.0 sphinx sphinxcontrib-spelling +numpydoc beautifulsoup4>=4.2.1 blosc bottleneck>=1.2.0