Hello community,
here is the log from the commit of package python-numpydoc for openSUSE:Factory
checked in at 2018-04-30 22:56:56
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Comparing /work/SRC/openSUSE:Factory/python-numpydoc (Old)
and /work/SRC/openSUSE:Factory/.python-numpydoc.new (New)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "python-numpydoc"
Mon Apr 30 22:56:56 2018 rev:8 rq:602336 version:0.8.0
Changes:
--------
--- /work/SRC/openSUSE:Factory/python-numpydoc/python-numpydoc.changes
2017-10-09 19:40:54.046888319 +0200
+++ /work/SRC/openSUSE:Factory/.python-numpydoc.new/python-numpydoc.changes
2018-04-30 22:59:06.932073930 +0200
@@ -1,0 +2,51 @@
+Sun Apr 29 04:11:15 UTC 2018 - a...@gmx.de
+
+- specfile:
+ * update copyright year
+ * require Jinja (from setup.py)
+ * always run tests
+
+- update to version 0.8.0:
+ * DOC: update URL to documentation in setup.py
+ * Use isdatadescriptor instead of isgetsetdescriptor
+ * Ensure reference renaming is parallel-safe (#136)
+ * Simplify and restructure README
+ * Automatically load autosummary (#143)
+ * FIX Handle case where description is empty in returns (#148)
+ * FIX handling of parameter names ending '_'
+ * Handle case where description is empty (#140)
+ * Correct deduplication logic
+ * Make sure case when class + method docstrings are combined is not
+ reprocessed
+ * Avoid reprocessing already numpydocced docstrings
+ * DOC Use .. deprecated for deprecation instead of .. note (#120)
+ * Add required arg to setup so that nose does not call it
+ * Cosmetic and efficiency improvements to replace_referneces (#132)
+ * Remove comment autosummary from _str_param_list
+ * Flake8
+ * Make version available to Python without dependencies; and to
+ Sphinx metadata
+ * Test use_blockquotes config
+ * Leading and trailing blank lines in parameter description should
+ not affect output
+ * Stricter comparison of whitespace in testing
+ * Corret search syntax
+ * Use definition lists rather than blockquotes
+ * Support from matplotlib import as alias for import matplotlib
+ * only recommend inline form
+ * add documentation on hyperlinks
+ * DOC: fix syntax error in deprecated of numpydoc_edit_link (#122)
+ * DOC Note on section ordering, and add missing sections
+ * DOC Fix link
+ * DOC: Restore working conf.py
+ * DOC: cross-link to github from documentation
+ * Add doc build requirements file for readthedocs
+ * Corrected rtd url
+ * Older versions of sphinx do not have imgmath
+ * DOC: pipe README.rst contents into "long_description", for PyPI
+ frontpage
+ * MAINT: update ReST formatting in README.
+ * Basic docs based on Numpy's HOW_TO_DOCUMENT.rst.txt
+ * Allow see also object ref to incorporate ~ prefix
+
+-------------------------------------------------------------------
Old:
----
numpydoc-0.7.0.tar.gz
New:
----
numpydoc-0.8.0.tar.gz
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Other differences:
------------------
++++++ python-numpydoc.spec ++++++
--- /var/tmp/diff_new_pack.DgaZk2/_old 2018-04-30 22:59:07.396057000 +0200
+++ /var/tmp/diff_new_pack.DgaZk2/_new 2018-04-30 22:59:07.400056854 +0200
@@ -1,7 +1,7 @@
#
# spec file for package python-numpydoc
#
-# Copyright (c) 2017 SUSE LINUX GmbH, Nuernberg, Germany.
+# Copyright (c) 2018 SUSE LINUX GmbH, Nuernberg, Germany.
#
# All modifications and additions to the file contributed by third parties
# remain the property of their copyright owners, unless otherwise agreed
@@ -16,28 +16,24 @@
#
-%bcond_without tests
-
%{?!python_module:%define python_module() python-%{**} python3-%{**}}
Name: python-numpydoc
-Version: 0.7.0
+Version: 0.8.0
Release: 0
Summary: Sphinx extension to support docstrings in Numpy format
License: BSD-3-Clause
Group: Development/Languages/Python
-Url: https://github.com/numpy/numpydoc
+URL: https://github.com/numpy/numpydoc
Source:
https://files.pythonhosted.org/packages/source/n/numpydoc/numpydoc-%{version}.tar.gz
+BuildRequires: %{python_module Sphinx >= 1.0.1}
BuildRequires: %{python_module devel >= 2.7.7}
+BuildRequires: %{python_module matplotlib}
+BuildRequires: %{python_module nose}
BuildRequires: %{python_module setuptools}
BuildRequires: fdupes
BuildRequires: python-rpm-macros
-%if %{with tests}
-BuildRequires: %{python_module Sphinx >= 1.0.1}
-BuildRequires: %{python_module matplotlib}
-BuildRequires: %{python_module nose}
-%endif
+Requires: python-Jinja2 >= 2.3
Requires: python-Sphinx >= 1.0.1
-BuildRoot: %{_tmppath}/%{name}-%{version}-build
BuildArch: noarch
%python_subpackages
@@ -56,14 +52,12 @@
%python_install
%python_expand %fdupes %{buildroot}%{$python_sitelib}
-%if %{with tests}
%check
%python_exec setup.py -q test
-%endif
%files %{python_files}
-%defattr(-,root,root,-)
-%doc LICENSE.txt README.rst
+%license LICENSE.txt
+%doc README.rst
%{python_sitelib}/numpydoc/
%{python_sitelib}/numpydoc-%{version}-py*.egg-info
++++++ numpydoc-0.7.0.tar.gz -> numpydoc-0.8.0.tar.gz ++++++
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/LICENSE.txt
new/numpydoc-0.8.0/LICENSE.txt
--- old/numpydoc-0.7.0/LICENSE.txt 2014-01-12 11:49:19.000000000 +0100
+++ new/numpydoc-0.8.0/LICENSE.txt 2018-03-30 06:00:21.000000000 +0200
@@ -1,11 +1,3 @@
--------------------------------------------------------------------------------
- The files
- - numpydoc.py
- - docscrape.py
- - docscrape_sphinx.py
- - phantom_import.py
- have the following license:
-
Copyright (C) 2008 Stefan van der Walt <ste...@mentat.za.net>, Pauli Virtanen
<p...@iki.fi>
Redistribution and use in source and binary forms, with or without
@@ -30,65 +22,3 @@
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 -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/PKG-INFO new/numpydoc-0.8.0/PKG-INFO
--- old/numpydoc-0.7.0/PKG-INFO 2017-06-20 11:53:10.000000000 +0200
+++ new/numpydoc-0.8.0/PKG-INFO 2018-03-31 01:49:05.000000000 +0200
@@ -1,12 +1,39 @@
Metadata-Version: 1.1
Name: numpydoc
-Version: 0.7.0
+Version: 0.8.0
Summary: Sphinx extension to support docstrings in Numpy format
-Home-page:
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
+Home-page: https://numpydoc.readthedocs.io
Author: Pauli Virtanen and others
Author-email: p...@iki.fi
License: BSD
-Description: UNKNOWN
+Description-Content-Type: UNKNOWN
+Description: .. image:: https://travis-ci.org/numpy/numpydoc.png?branch=master
+ :target: https://travis-ci.org/numpy/numpydoc/
+
+ .. |docs| image::
https://readthedocs.org/projects/numpydoc/badge/?version=latest
+ :alt: Documentation Status
+ :scale: 100%
+ :target: https://numpydoc.readthedocs.io/en/latest/?badge=latest
+
+
+ =====================================
+ numpydoc -- Numpy's Sphinx extensions
+ =====================================
+
+ This package provides the ``numpydoc`` Sphinx extension for handling
+ docstrings formatted according to the `NumPy documentation format
+
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`__.
+ The extension also adds the code description directives
+ ``np:function``, ``np-c:function``, etc.
+
+ For usage information, please refer to the `documentation
+ <https://numpydoc.readthedocs.io/>`_.
+
+ The `numpydoc docstring guide
+ <https://numpydoc.readthedocs.io/en/latest/format.html>`_ explains how
+ to write docs formatted for this extension, and the `user guide
+ <https://numpydoc.readthedocs.io>`_ explains how to use it with Sphinx.
+
Keywords: sphinx numpy
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/README.rst
new/numpydoc-0.8.0/README.rst
--- old/numpydoc-0.7.0/README.rst 2015-04-07 22:56:26.000000000 +0200
+++ new/numpydoc-0.8.0/README.rst 2018-03-30 06:00:21.000000000 +0200
@@ -1,65 +1,26 @@
.. image:: https://travis-ci.org/numpy/numpydoc.png?branch=master
:target: https://travis-ci.org/numpy/numpydoc/
+.. |docs| image::
https://readthedocs.org/projects/numpydoc/badge/?version=latest
+ :alt: Documentation Status
+ :scale: 100%
+ :target: https://numpydoc.readthedocs.io/en/latest/?badge=latest
+
+
=====================================
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.
-
-See `A Guide to NumPy/SciPy Documentation
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
-for how to write docs that use this extension.
-
-
-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.
- ``True`` by default.
-
-- numpydoc_show_inherited_class_members: bool
-
- Whether to show all inherited members of a class in the Methods and
Attributes
- sections automatically. If it's false, inherited members won't shown.
- ``True`` by default.
-
-- 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.
- ``True`` by default.
-
-- numpydoc_edit_link: bool (DEPRECATED -- edit your HTML template instead)
-
- Whether to insert an edit link after docstrings.
+This package provides the ``numpydoc`` Sphinx extension for handling
+docstrings formatted according to the `NumPy documentation format
+<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`__.
+The extension also adds the code description directives
+``np:function``, ``np-c:function``, etc.
+
+For usage information, please refer to the `documentation
+<https://numpydoc.readthedocs.io/>`_.
+
+The `numpydoc docstring guide
+<https://numpydoc.readthedocs.io/en/latest/format.html>`_ explains how
+to write docs formatted for this extension, and the `user guide
+<https://numpydoc.readthedocs.io>`_ explains how to use it with Sphinx.
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/numpydoc/__init__.py
new/numpydoc-0.8.0/numpydoc/__init__.py
--- old/numpydoc-0.7.0/numpydoc/__init__.py 2017-06-20 11:32:51.000000000
+0200
+++ new/numpydoc-0.8.0/numpydoc/__init__.py 2018-03-31 01:45:04.000000000
+0200
@@ -1,5 +1,8 @@
from __future__ import division, absolute_import, print_function
-__version__ = '0.7.0'
+__version__ = '0.8.0'
-from .numpydoc import setup
+
+def setup(app, *args, **kwargs):
+ from .numpydoc import setup
+ return setup(app, *args, **kwargs)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/numpydoc/docscrape.py
new/numpydoc-0.8.0/numpydoc/docscrape.py
--- old/numpydoc-0.7.0/numpydoc/docscrape.py 2017-06-20 11:30:40.000000000
+0200
+++ new/numpydoc-0.8.0/numpydoc/docscrape.py 2018-03-31 01:39:19.000000000
+0200
@@ -13,6 +13,15 @@
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.
@@ -98,6 +107,12 @@
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': [''],
@@ -136,7 +151,7 @@
def __setitem__(self, key, val):
if key not in self._parsed_data:
- warn("Unknown section %s" % key)
+ self._error_location("Unknown section %s" % key, error=False)
else:
self._parsed_data[key] = val
@@ -208,12 +223,14 @@
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<role>\w+):`(?P<name>[a-zA-Z0-9_.-]+)`|"
+ _name_rgx = re.compile(r"^\s*(:(?P<role>\w+):"
+ r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_.-]+)`|"
r" (?P<name2>[a-zA-Z0-9_.-]+))\s*", re.X)
def _parse_see_also(self, content):
@@ -331,19 +348,8 @@
section = (s.capitalize() for s in section.split(' '))
section = ' '.join(section)
if self.get(section):
- if hasattr(self, '_obj'):
- # we know where the docs came from:
- try:
- filename = inspect.getsourcefile(self._obj)
- except TypeError:
- filename = None
- msg = ("The section %s appears twice in "
- "the docstring of %s in %s." %
- (section, self._obj, filename))
- raise ValueError(msg)
- else:
- msg = ("The section %s appears twice" % section)
- raise ValueError(msg)
+ self._error_location("The section %s appears twice"
+ % section)
if section in ('Parameters', 'Returns', 'Yields', 'Raises',
'Warns', 'Other Parameters', 'Attributes',
@@ -356,6 +362,20 @@
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='-'):
@@ -394,7 +414,8 @@
out += ['%s : %s' % (param, param_type)]
else:
out += [param]
- out += self._str_indent(desc)
+ if desc and ''.join(desc).strip():
+ out += self._str_indent(desc)
out += ['']
return out
@@ -592,7 +613,7 @@
return [name for name, func in inspect.getmembers(self._cls)
if (not name.startswith('_') and
(func is None or isinstance(func, property) or
- inspect.isgetsetdescriptor(func))
+ inspect.isdatadescriptor(func))
and self._is_show_member(name))]
def _is_show_member(self, name):
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/numpydoc/docscrape_sphinx.py
new/numpydoc-0.8.0/numpydoc/docscrape_sphinx.py
--- old/numpydoc-0.7.0/numpydoc/docscrape_sphinx.py 2017-06-18
12:51:07.000000000 +0200
+++ new/numpydoc-0.8.0/numpydoc/docscrape_sphinx.py 2018-03-31
01:39:19.000000000 +0200
@@ -21,6 +21,9 @@
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)
@@ -28,6 +31,7 @@
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.template = config.get('template', None)
if self.template is None:
@@ -63,37 +67,147 @@
return self['Extended Summary'] + ['']
def _str_returns(self, name='Returns'):
+ 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(['**%s** : %s' % (param.strip(),
- param_type)])
+ out += self._str_indent([typed_fmt % (param.strip(),
+ param_type)])
else:
- out += self._str_indent([param.strip()])
- if desc:
+ out += self._str_indent([untyped_fmt % param.strip()])
+ if desc and self.use_blockquotes:
out += ['']
- out += self._str_indent(desc, 8)
+ elif not desc:
+ desc = ['..']
+ out += self._str_indent(desc, 8)
out += ['']
return out
- def _str_param_list(self, name):
+ 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()
+ # XXX: If changing the following, please check the rendering when param
+ # ends with '_', e.g. 'word_'
+ # See https://github.com/numpy/numpydoc/pull/144
+ display_param = '**%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' % (param.strip(),
- param_type)])
+ out += self._str_indent(['%s : %s' % (display_param,
+ param_type)])
else:
- out += self._str_indent(['**%s**' % param.strip()])
- if desc:
+ out += self._str_indent([display_param])
+ if desc and self.use_blockquotes:
out += ['']
- out += self._str_indent(desc, 8)
+ elif not desc:
+ # empty definition
+ desc = ['..']
+ out += self._str_indent(desc, 8)
out += ['']
+
return out
@property
@@ -127,10 +241,10 @@
param_obj = getattr(self._obj, param, None)
if not (callable(param_obj)
or isinstance(param_obj, property)
- or inspect.isgetsetdescriptor(param_obj)):
+ or inspect.isdatadescriptor(param_obj)):
param_obj = None
- if param_obj and (pydoc.getdoc(param_obj) or not desc):
+ if param_obj and pydoc.getdoc(param_obj):
# Referenced object has a docstring
autosum += [" %s%s" % (prefix, param)]
else:
@@ -160,7 +274,6 @@
out = []
if self[name]:
out += self._str_header(name)
- out += ['']
content = textwrap.dedent("\n".join(self[name])).split("\n")
out += content
out += ['']
@@ -179,6 +292,7 @@
if self['Warnings']:
out = ['.. warning::', '']
out += self._str_indent(self['Warnings'])
+ out += ['']
return out
def _str_index(self):
@@ -195,6 +309,7 @@
out += [' single: %s' % (', '.join(references))]
else:
out += [' %s: %s' % (section, ','.join(references))]
+ out += ['']
return out
def _str_references(self):
@@ -222,7 +337,7 @@
def _str_examples(self):
examples_str = "\n".join(self['Examples'])
- if (self.use_plots and 'import matplotlib' in examples_str
+ if (self.use_plots and re.search(IMPORT_MATPLOTLIB_RE, examples_str)
and 'plot::' not in examples_str):
out = []
out += self._str_header('Examples')
@@ -250,7 +365,8 @@
'notes': self._str_section('Notes'),
'references': self._str_references(),
'examples': self._str_examples(),
- 'attributes': self._str_member_list('Attributes'),
+ 'attributes': self._str_param_list('Attributes',
+ fake_autosummary=True),
'methods': self._str_member_list('Methods'),
}
ns = dict((k, '\n'.join(v)) for k, v in ns.items())
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/numpydoc/numpydoc.py
new/numpydoc-0.8.0/numpydoc/numpydoc.py
--- old/numpydoc-0.7.0/numpydoc/numpydoc.py 2017-06-20 11:30:40.000000000
+0200
+++ new/numpydoc-0.8.0/numpydoc/numpydoc.py 2018-03-30 06:00:21.000000000
+0200
@@ -21,14 +21,19 @@
import sys
import re
import pydoc
-import sphinx
import inspect
import collections
+import hashlib
+
+from docutils.nodes import citation, Text
+import sphinx
+from sphinx.addnodes import pending_xref, desc_content
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
@@ -36,35 +41,77 @@
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 = []
+HASH_LEN = 12
+
+
+def rename_references(app, what, name, obj, options, lines):
+ # decorate reference numbers so that there are no duplicates
+ # these are later undecorated in the doctree, in relabel_references
+ 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.append(m.group(1))
+ references.add(m.group(1))
if references:
- for i, line in enumerate(lines):
- for r in references:
- if re.match(sixu('^\\d+$'), r):
- new_r = sixu("R%d") % (reference_offset[0] + int(r))
- else:
- new_r = sixu("%s%d") % (r, reference_offset[0])
+ # we use a hash to mangle the reference name to avoid invalid names
+ sha = hashlib.sha256()
+ sha.update(name.encode('utf8'))
+ prefix = 'R' + sha.hexdigest()[:HASH_LEN]
+
+ for r in references:
+ new_r = prefix + '-' + r
+ 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)
+
+def _ascend(node, cls):
+ while node and not isinstance(node, cls):
+ node = node.parent
+ return node
+
+
+def relabel_references(app, doc):
+ # Change 'hash-ref' to 'ref' in label text
+ for citation_node in doc.traverse(citation):
+ if _ascend(citation_node, desc_content) is None:
+ # no desc node in ancestry -> not in a docstring
+ # XXX: should we also somehow check it's in a References section?
+ continue
+ label_node = citation_node[0]
+ prefix, _, new_label = label_node[0].astext().partition('-')
+ assert len(prefix) == HASH_LEN + 1
+ new_text = Text(new_label)
+ label_node.replace(label_node[0], new_text)
+
+ for id in citation_node['backrefs']:
+ ref = doc.ids[id]
+ ref_text = ref[0]
+
+ # Sphinx has created pending_xref nodes with [reftext] text.
+ def matching_pending_xref(node):
+ return (isinstance(node, pending_xref) and
+ node[0].astext() == '[%s]' % ref_text)
+
+ for xref_node in ref.parent.traverse(matching_pending_xref):
+ xref_node.replace(xref_node[0], Text('[%s]' % new_text))
+ ref.replace(ref_text, new_text.copy())
+
+
+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,
@@ -99,6 +146,8 @@
# 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__`
@@ -129,8 +178,10 @@
app.connect('autodoc-process-docstring', mangle_docstrings)
app.connect('autodoc-process-signature', mangle_signature)
+ app.connect('doctree-read', relabel_references)
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)
@@ -140,7 +191,10 @@
app.add_domain(NumpyPythonDomain)
app.add_domain(NumpyCDomain)
- metadata = {'parallel_read_safe': True}
+ app.setup_extension('sphinx.ext.autosummary')
+
+ metadata = {'version': __version__,
+ 'parallel_read_safe': True}
return metadata
#
------------------------------------------------------------------------------
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/numpydoc/tests/test_docscrape.py
new/numpydoc-0.8.0/numpydoc/tests/test_docscrape.py
--- old/numpydoc-0.7.0/numpydoc/tests/test_docscrape.py 2017-06-20
11:30:41.000000000 +0200
+++ new/numpydoc-0.8.0/numpydoc/tests/test_docscrape.py 2018-03-31
01:39:19.000000000 +0200
@@ -1,8 +1,10 @@
# -*- encoding:utf-8 -*-
from __future__ import division, absolute_import, print_function
+import re
import sys
import textwrap
+import warnings
import jinja2
@@ -13,10 +15,12 @@
ParseError
)
from numpydoc.docscrape_sphinx import (SphinxDocString, SphinxClassDoc,
- SphinxFunctionDoc)
+ SphinxFunctionDoc, get_doc_object)
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:
@@ -52,7 +56,7 @@
-------
out : ndarray
The drawn samples, arranged according to `shape`. If the
- shape given is (m,n,...), then the shape of `out` is is
+ 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
@@ -60,6 +64,7 @@
list of str
This is not a real return value. It exists to test
anonymous return values.
+ no_description
Other Parameters
----------------
@@ -151,13 +156,16 @@
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'])
@@ -165,7 +173,8 @@
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][-2] == ' (1+2+3)/3'
+ assert doc['Parameters'][0][-1][-1] == ' (1+2+3)/3'
+
def test_other_parameters():
assert_equal(len(doc['Other Parameters']), 1)
@@ -174,8 +183,9 @@
assert_equal(arg_type, 'parrot')
assert desc[0].startswith('A parrot off its mortal coil')
+
def test_returns():
- assert_equal(len(doc['Returns']), 2)
+ assert_equal(len(doc['Returns']), 3)
arg, arg_type, desc = doc['Returns'][0]
assert_equal(arg, 'out')
assert_equal(arg_type, 'ndarray')
@@ -188,6 +198,12 @@
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)
@@ -200,6 +216,7 @@
assert desc[0].startswith('The number of')
assert desc[0].endswith(end)
+
def test_returnyield():
doc_text = """
Test having returns and yields.
@@ -289,31 +306,44 @@
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 non_blank_line_by_line_compare(a,b):
+
+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 a.split('\n') if l.strip()]
- b = [l.rstrip() for l in b.split('\n') if l.strip()]
+ 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.
- non_blank_line_by_line_compare(str(doc),
+ line_by_line_compare(str(doc),
"""numpy.multivariate_normal(mean, cov, shape=None, spam=None)
Draw values from a multivariate normal distribution with specified
@@ -330,7 +360,6 @@
.. math::
(1+2+3)/3
-
cov : (N, N) ndarray
Covariance matrix of the distribution.
shape : tuple of ints
@@ -342,7 +371,7 @@
-------
out : ndarray
The drawn samples, arranged according to `shape`. If the
- shape given is (m,n,...), then the shape of `out` is is
+ 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
@@ -350,6 +379,7 @@
list of str
This is not a real return value. It exists to test
anonymous return values.
+no_description
Other Parameters
----------------
@@ -372,6 +402,7 @@
See Also
--------
+
`some`_, `other`_, `funcs`_
`otherfunc`_
@@ -423,7 +454,7 @@
def test_yield_str():
- non_blank_line_by_line_compare(str(doc_yields),
+ line_by_line_compare(str(doc_yields),
"""Test generator
Yields
@@ -440,7 +471,7 @@
def test_sphinx_str():
sphinx_doc = SphinxDocString(doc_txt)
- non_blank_line_by_line_compare(str(sphinx_doc),
+ line_by_line_compare(str(sphinx_doc),
"""
.. index:: random
single: random;distributions, random;gauss
@@ -454,7 +485,6 @@
:Parameters:
**mean** : (N,) ndarray
-
Mean of the N-dimensional distribution.
.. math::
@@ -462,11 +492,9 @@
(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).
@@ -474,35 +502,33 @@
:Returns:
**out** : ndarray
-
The drawn samples, arranged according to `shape`. If the
- shape given is (m,n,...), then the shape of `out` is is
+ 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
-
+ **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::
@@ -565,21 +591,18 @@
def test_sphinx_yields_str():
sphinx_doc = SphinxDocString(doc_yields_txt)
- non_blank_line_by_line_compare(str(sphinx_doc),
+ line_by_line_compare(str(sphinx_doc),
"""Test generator
:Yields:
**a** : int
-
The number of apples.
**b** : int
-
The number of bananas.
- int
-
+ **int**
The number of unknowns.
""")
@@ -595,15 +618,18 @@
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)')
@@ -614,14 +640,17 @@
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()
@@ -637,18 +666,21 @@
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(
"""
@@ -663,21 +695,23 @@
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']) == 12
+ 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'):
+ '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':
+ elif func == 'baz.obj_q' or func == '~baz.obj_r':
assert role == 'obj'
elif func == 'class_j':
assert role == 'class'
@@ -726,12 +760,45 @@
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.<locals>.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')
@@ -762,6 +829,7 @@
assert isinstance(doc['Summary'][0], str)
assert doc['Summary'][0] == 'öäöäöäöäöåååå'
+
def test_plot_examples():
cfg = dict(use_plots=True)
@@ -777,6 +845,15 @@
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
@@ -785,6 +862,47 @@
""", 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):
@@ -866,6 +984,7 @@
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
@@ -889,6 +1008,7 @@
f : callable ``f(t, y, *f_args)``
Aaa.
jac : callable ``jac(t, y, *jac_args)``
+
Bbb.
Attributes
@@ -897,8 +1017,17 @@
Current time.
y : ndarray
Current variable values.
- x : float
- Some parameter
+
+ * 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
-------
@@ -911,9 +1040,10 @@
For usage examples, see `ode`.
"""
+
def test_class_members_doc():
doc = ClassDoc(None, class_doc_txt)
- non_blank_line_by_line_compare(str(doc),
+ line_by_line_compare(str(doc),
"""
Foo
@@ -934,58 +1064,109 @@
Current time.
y : ndarray
Current variable values.
- x : float
- Some parameter
+
+ * 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 x(self):
+ 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)
- non_blank_line_by_line_compare(str(doc),
+ 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`.
- .. rubric:: Attributes
+ :Attributes:
- .. autosummary::
- :toctree:
+ **t** : float
+ Current time.
- x
+ **y** : ndarray
+ Current variable values.
- ===== ==========
- **t** (float) Current time.
- **y** (ndarray) Current variable values.
- ===== ==========
+ * hello
+ * world
+
+ :obj:`an_attribute <an_attribute>` : float
+ Test attribute
+
+ **no_docstring** : str
+ But a description
+
+ **no_docstring2** : str
+ ..
+
+ :obj:`multiline_sentence <multiline_sentence>`
+ This is a sentence.
+
+ :obj:`midword_period <midword_period>`
+ The sentence for numpy.org.
+
+ :obj:`no_period <no_period>`
+ This does not have a period
.. rubric:: Methods
@@ -997,29 +1178,52 @@
""")
+
def test_templated_sections():
doc = SphinxClassDoc(None, class_doc_txt,
- config={'template':
jinja2.Template('{{examples}}{{parameters}}')})
- non_blank_line_by_line_compare(str(doc),
+ 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.
""")
+def test_nonstandard_property():
+ # test discovery of a property that does not satisfy isinstace(..,
property)
+
+ class SpecialProperty(object):
+
+ def __init__(self, axis=0, doc=""):
+ self.axis = axis
+ self.__doc__ = doc
+
+ def __get__(self, obj, type):
+ if obj is None:
+ # Only instances have actual _data, not classes
+ return self
+ else:
+ return obj._data.axes[self.axis]
+
+ def __set__(self, obj, value):
+ obj._set_axis(self.axis, value)
+
+ class Dummy:
+
+ attr = SpecialProperty(doc="test attribute")
+
+ doc = get_doc_object(Dummy)
+ assert "test attribute" in str(doc)
if __name__ == "__main__":
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/numpydoc-0.7.0/setup.py new/numpydoc-0.8.0/setup.py
--- old/numpydoc-0.7.0/setup.py 2017-06-18 12:59:18.000000000 +0200
+++ new/numpydoc-0.8.0/setup.py 2018-03-31 01:45:04.000000000 +0200
@@ -1,25 +1,35 @@
from __future__ import division, print_function
import sys
+import os
+import setuptools # may monkeypatch distutils in some versions. # noqa
from distutils.command.sdist import sdist
-import setuptools
from distutils.core import setup
+from numpydoc import __version__ as version
+
if sys.version_info[:2] < (2, 7) or (3, 0) <= sys.version_info[0:2] < (3, 4):
raise RuntimeError("Python version 2.7 or >= 3.4 required.")
-with open('numpydoc/__init__.py') as fid:
- for line in fid:
- if line.startswith('__version__'):
- version = line.strip().split()[-1][1:-1]
- break
+
+def read(fname):
+ """Utility function to get README.rst into long_description.
+
+ ``long_description`` is what ends up on the PyPI front page.
+ """
+ with open(os.path.join(os.path.dirname(__file__), fname)) as f:
+ contents = f.read()
+
+ return contents
+
setup(
name="numpydoc",
packages=["numpydoc"],
version=version,
description="Sphinx extension to support docstrings in Numpy format",
+ long_description=read('README.rst'),
# classifiers from http://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers=["Development Status :: 4 - Beta",
"Environment :: Plugins",
@@ -35,7 +45,7 @@
keywords="sphinx numpy",
author="Pauli Virtanen and others",
author_email="p...@iki.fi",
-
url="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt";,
+ url="https://numpydoc.readthedocs.io";,
license="BSD",
install_requires=["sphinx >= 1.2.3", 'Jinja2>=2.3'],
package_data={'numpydoc': ['tests/test_*.py', 'templates/*.rst']},
