Merge branch 'master' into deflist

Author: jnothman

.travis.yml

@@ -12,6 +12,7 @@ cache:
   directories:
     - $HOME/.cache/pip
 before_install:
+  - sudo apt-get install texlive texlive-latex-extra latexmk
   - pip install --upgrade pip setuptools  # Upgrade pip and setuptools to get ones with `wheel` support
   - pip install --find-links http://wheels.astropy.org/ --find-links http://wheels2.astropy.org/ --trusted-host wheels.astropy.org --trusted-host wheels2.astropy.org --use-wheel nose numpy matplotlib ${SPHINX_SPEC}
 script:

doc/conf.py

@@ -38,6 +38,7 @@
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.pngmath',
@@ -223,7 +224,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ('index', '.tex', u'numpydoc Documentation',
+    ('index', 'numpydoc.tex', u'numpydoc Documentation',
      u'Numpydoc maintainers', 'manual'),
 ]
 

doc/format.rst

@@ -88,7 +88,12 @@ facilitate reading the docstrings in text terminals.
 
 Sections
 --------
-The sections of the docstring are:
+
+The docstring consists of a number of sections separated by headings (except
+for the deprecation warning). Each heading should be underlined in hyphens, and
+the section ordering should be consistent with the description below.
+
+The sections of a function's docstring are:
 
 1. **Short summary**
 
@@ -127,12 +132,12 @@ The sections of the docstring are:
 
    * New recommended way of obtaining the same functionality.
 
-   This section should use the note Sphinx directive instead of an
+   This section should use the ``deprecated`` Sphinx directive instead of an
    underlined section header.
 
    ::
 
-     .. note:: Deprecated in NumPy 1.6.0
+     .. deprecated:: 1.6.0
                `ndobj_old` will be removed in NumPy 2.0.0, it is replaced by
                `ndobj_new` because the latter works also with array subclasses.
 
@@ -264,7 +269,16 @@ The sections of the docstring are:
    This section should be used judiciously, i.e., only for errors
    that are non-obvious or have a large chance of getting raised.
 
-9. **See Also**
+9. **Warns**
+
+   An optional section detailing which warnings get raised and
+   under what conditions, formatted similarly to Raises.
+
+10. **Warnings**
+
+   An optional section with cautions to the user in free text/reST.
+
+11. **See Also**
 
    An optional section used to refer to related code.  This section
    can be very useful, but should be used judiciously.  The goal is to
@@ -303,7 +317,7 @@ The sections of the docstring are:
      func_b, func_c_, func_d
      func_e
 
-10. **Notes**
+12. **Notes**
 
     An optional section that provides additional information about the
     code, possibly including a discussion of the algorithm. This
@@ -348,7 +362,7 @@ The sections of the docstring are:
     where filename is a path relative to the reference guide source
     directory.
 
-11. **References**
+13. **References**
 
     References cited in the **notes** section may be listed here,
     e.g. if you cited the article below using the text ``[1]_``,
@@ -373,7 +387,7 @@ The sections of the docstring are:
     should not be required to understand it.  References are numbered, starting
     from one, in the order in which they are cited.
 
-12. **Examples**
+14. **Examples**
 
     An optional section for examples, using the `doctest
     <http://docs.python.org/library/doctest.html>`_ format.
@@ -597,6 +611,19 @@ Other points to keep in mind
   (i.e. scalar types, sequence types), those arguments can be documented
   with type `array_like`.
 
+* Links : If you need to include hyperlinks in your docstring, note that
+  some docstring sections are not parsed as standard reST, and in these
+  sections, numpydoc may become confused by hyperlink targets such as::
+
+      .. _Example: http://www.example.com
+
+  If the Sphinx build issues a warning of the form
+  ``WARNING: Unknown target name: "example"``, then that is what is happening.
+  To avoid this problem, use the inline hyperlink form::
+
+      `Example <http://www.example.com>`_
+
+
 Common reST concepts
 --------------------
 For paragraphs, indentation is significant and indicates indentation in the

doc/install.rst

@@ -19,11 +19,7 @@ The following options can be set in your Sphinx ``conf.py``:
 
 numpydoc_use_plots : bool
   Whether to produce ``plot::`` directives for Examples sections that
-  contain ``import matplotlib``.
-numpydoc_use_blockqutoes : bool
-  Until version 0.8, parameter definitions were shown as blockquotes, rather
-  than in a definition list.  If your styling requires blockquotes, switch
-  this config option to True.  This option will be removed in version 0.10.
+  contain ``import matplotlib`` or ``from matplotlib import``.
 numpydoc_show_class_members : bool
   Whether to show all members of a class in the Methods and Attributes
   sections automatically.
@@ -42,7 +38,11 @@ numpydoc_citation_re : str
   should be mangled to avoid conflicts due to
   duplication across the documentation.  Defaults
   to ``[\w-]+``.
+numpydoc_use_blockqutoes : bool
+  Until version 0.8, parameter definitions were shown as blockquotes, rather
+  than in a definition list.  If your styling requires blockquotes, switch
+  this config option to True.  This option will be removed in version 0.10.
 numpydoc_edit_link : bool
-  .. deprecated: edit your HTML template instead
+  .. deprecated:: edit your HTML template instead
 
   Whether to insert an edit link after docstrings.

numpydoc/docscrape.py

@@ -229,7 +229,8 @@ def _parse_param_list(self, content):
 
         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):

numpydoc/docscrape_sphinx.py

@@ -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)
@@ -88,10 +91,10 @@ def _str_returns(self, name='Returns'):
                 out += ['']
         return out
 
-    def _process_param(self, param, desc, autosum):
+    def _process_param(self, param, desc, fake_autosummary):
         """Determine how to display a parameter
 
-        Emulates autosummary behavior if autosum is not None.
+        Emulates autosummary behavior if fake_autosummary
 
         Parameters
         ----------
@@ -100,12 +103,9 @@ def _process_param(self, param, desc, autosum):
         desc : list of str
             The parameter description as given in the docstring. This is
             ignored when autosummary logic applies.
-        autosum : list or None
-            If a list, autosummary-style behaviour will apply for params
+        fake_autosummary : bool
+            If True, autosummary-style behaviour will apply for params
             that are attributes of the class and have a docstring.
-            Names for autosummary generation will be appended to this list.
-
-            If None, autosummary is disabled.
 
         Returns
         -------
@@ -128,7 +128,7 @@ def _process_param(self, param, desc, autosum):
         param = param.strip()
         display_param = ('**%s**' if self.use_blockquotes else '%s') % param
 
-        if autosum is None:
+        if not fake_autosummary:
             return display_param, desc
 
         param_obj = getattr(self._obj, param, None)
@@ -150,7 +150,6 @@ def _process_param(self, param, desc, autosum):
             link_prefix = ''
 
         # Referenced object has a docstring
-        autosum.append("    %s%s" % (autosum_prefix, param))
         display_param = ':obj:`%s <%s%s>`' % (param,
                                               link_prefix,
                                               param)
@@ -190,15 +189,11 @@ def _str_param_list(self, name, fake_autosummary=False):
         """
         out = []
         if self[name]:
-            if fake_autosummary:
-                autosum = []
-            else:
-                autosum = None
-
             out += self._str_field_list(name)
             out += ['']
             for param, param_type, desc in self[name]:
-                display_param, desc = self._process_param(param, desc, autosum)
+                display_param, desc = self._process_param(param, desc,
+                                                          fake_autosummary)
 
                 if param_type:
                     out += self._str_indent(['%s : %s' % (display_param,
@@ -211,14 +206,6 @@ def _str_param_list(self, name, fake_autosummary=False):
                     out += self._str_indent(desc, 8)
                 out += ['']
 
-            if fake_autosummary and autosum:
-                if self.class_members_toctree:
-                    autosum.insert(0, '    :toctree:')
-                autosum.insert(0, '.. autosummary::')
-                out += ['..', '    HACK to make autogen generate docs:']
-                out += self._str_indent(autosum, 4)
-                out += ['']
-
         return out
 
     @property
@@ -348,7 +335,7 @@ def _str_references(self):
     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')

numpydoc/numpydoc.py

@@ -39,30 +39,36 @@
 def rename_references(app, what, name, obj, options, lines,
                       reference_offset=[0]):
     # replace reference numbers so that there are no duplicates
-    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])
+        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)
+        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,
@@ -100,6 +106,8 @@ def mangle_docstrings(app, what, name, obj, options, lines):
     # 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__`

numpydoc/tests/test_docscrape.py

@@ -685,21 +685,23 @@ def test_see_also():
     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'
@@ -830,6 +832,15 @@ def test_plot_examples():
     """, 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
     --------
@@ -1146,15 +1157,6 @@ def no_period(self):
         :obj:`no_period <no_period>`
             This does not have a period
 
-    ..
-        HACK to make autogen generate docs:
-        .. autosummary::
-            :toctree:
-            an_attribute
-            multiline_sentence
-            midword_period
-            no_period
-
     .. rubric:: Methods
 
     =====  ==========