Merge remote-tracking branch 'upstream/master' into attributes_as_param_list

Author: jorisvandenbossche

.travis.yml

@@ -2,26 +2,29 @@
 #   http://lint.travis-ci.org/
 language: python
 sudo: false
-python:
-  - 3.6
-  - 2.7
 env:
   - SPHINX_SPEC="Sphinx==1.2.3"
   - SPHINX_SPEC="Sphinx"
+matrix:
+  include:
+    - python: 3.6
+    - python: 2.7
+      env:
+        - SPHINXOPTS='-W'
 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}
+  - pip install pytest numpy matplotlib ${SPHINX_SPEC}
 script:
   - |
     python setup.py sdist
     cd dist
     pip install numpydoc* -v
-  - nosetests numpydoc
+  - pytest --pyargs numpydoc
   - |
     cd ../doc
-    make html
-    make latexpdf
+    make SPHINXOPTS=$SPHINXOPTS html
+    make SPHINXOPTS=$SPHINXOPTS latexpdf

README.rst

@@ -12,8 +12,7 @@ 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>`__.
+docstrings formatted according to the NumPy documentation format.
 The extension also adds the code description directives
 ``np:function``, ``np-c:function``, etc.
 

doc/conf.py

@@ -41,13 +41,19 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
-    'sphinx.ext.pngmath',
     'sphinx.ext.todo',
     'numpydoc',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
 ]
 
+try:
+    import sphinx.ext.imgmath  # noqa
+except ImportError:
+    extensions.append('sphinx.ext.pngmath')
+else:
+    extensions.append('sphinx.ext.imgmath')
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -149,13 +155,12 @@
     html_sidebars = {}
 
 html_title = "%s v%s Manual" % (project, version)
-html_static_path = ['_static']
 html_last_updated_fmt = '%b %d, %Y'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []  # ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -264,5 +269,5 @@
 # Example configuration for intersphinx: refer to the Python standard library.
 intersphinx_mapping = {
     'python': ('http://docs.python.org/', None),
-    'scikit-learn': ('http://scikit-learn.org/stable/', None),
+    'scikitlearn': ('http://scikit-learn.org/stable/', None),
 }

doc/example.py

@@ -93,7 +93,7 @@ def foo(var1, var2, long_var_name='hi'):
 
     .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
 
-    And even use a greek symbol like :math:`omega` inline.
+    And even use a Greek symbol like :math:`\omega` inline.
 
     References
     ----------

doc/format.rst

@@ -119,6 +119,8 @@ The sections of a function's docstring are:
 
      """
 
+.. highlight:: rst
+
 2. **Deprecation warning**
 
    A section (use if applicable) to warn users that the object is deprecated.
@@ -250,13 +252,21 @@ The sections of a function's docstring are:
    Support for the **Yields** section was added in `numpydoc
    <https://github.com/numpy/numpydoc>`_ version 0.6.
 
-7. **Other Parameters**
+7. **Receives**
+
+   Explanation of parameters passed to a generator's ``.send()`` method,
+   formatted as for Parameters, above.  Since, like for Yields and Returns, a
+   single object is always passed to the method, this may describe either the
+   single parameter, or positional arguments passed as a tuple.  If a docstring
+   includes Receives it must also include Yields.
+
+8. **Other Parameters**
 
    An optional section used to describe infrequently used parameters.
    It should only be used if a function has a large number of keyword
    parameters, to prevent cluttering the **Parameters** section.
 
-8. **Raises**
+9. **Raises**
 
    An optional section detailing which errors get raised and under
    what conditions::
@@ -269,55 +279,55 @@ The sections of a function's 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. **Warns**
+10. **Warns**
 
    An optional section detailing which warnings get raised and
    under what conditions, formatted similarly to Raises.
 
-10. **Warnings**
+11. **Warnings**
 
-   An optional section with cautions to the user in free text/reST.
+    An optional section with cautions to the user in free text/reST.
 
-11. **See Also**
+12. **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
-   direct users to other functions they may not be aware of, or have
-   easy means of discovering (by looking at the module docstring, for
-   example).  Routines whose docstrings further explain parameters
-   used by this function are good candidates.
+    An optional section used to refer to related code.  This section
+    can be very useful, but should be used judiciously.  The goal is to
+    direct users to other functions they may not be aware of, or have
+    easy means of discovering (by looking at the module docstring, for
+    example).  Routines whose docstrings further explain parameters
+    used by this function are good candidates.
 
-   As an example, for ``numpy.mean`` we would have::
+    As an example, for ``numpy.mean`` we would have::
 
-     See Also
-     --------
-     average : Weighted average
+      See Also
+      --------
+      average : Weighted average
 
-   When referring to functions in the same sub-module, no prefix is
-   needed, and the tree is searched upwards for a match.
+    When referring to functions in the same sub-module, no prefix is
+    needed, and the tree is searched upwards for a match.
 
-   Prefix functions from other sub-modules appropriately.  E.g.,
-   whilst documenting the ``random`` module, refer to a function in
-   ``fft`` by
+    Prefix functions from other sub-modules appropriately.  E.g.,
+    whilst documenting the ``random`` module, refer to a function in
+    ``fft`` by
 
-   ::
+    ::
 
-     fft.fft2 : 2-D fast discrete Fourier transform
+      fft.fft2 : 2-D fast discrete Fourier transform
 
-   When referring to an entirely different module::
+    When referring to an entirely different module::
 
-     scipy.random.norm : Random variates, PDFs, etc.
+      scipy.random.norm : Random variates, PDFs, etc.
 
-   Functions may be listed without descriptions, and this is
-   preferable if the functionality is clear from the function name::
+    Functions may be listed without descriptions, and this is
+    preferable if the functionality is clear from the function name::
 
-     See Also
-     --------
-     func_a : Function a with its description.
-     func_b, func_c_, func_d
-     func_e
+      See Also
+      --------
+      func_a : Function a with its description.
+      func_b, func_c_, func_d
+      func_e
 
-12. **Notes**
+13. **Notes**
 
     An optional section that provides additional information about the
     code, possibly including a discussion of the algorithm. This
@@ -362,7 +372,7 @@ The sections of a function's docstring are:
     where filename is a path relative to the reference guide source
     directory.
 
-13. **References**
+14. **References**
 
     References cited in the **notes** section may be listed here,
     e.g. if you cited the article below using the text ``[1]_``,
@@ -374,7 +384,7 @@ The sections of a function's docstring are:
          and neural-network techniques," Computers & Geosciences, vol. 22,
          pp. 585-588, 1996.
 
-    which renders as
+    which renders as [1]_:
 
     .. [1] O. McNoleg, "The integration of GIS, remote sensing,
        expert systems and adaptive co-kriging for environmental habitat
@@ -393,7 +403,9 @@ The sections of a function's docstring are:
         docstring, the table markup will be broken by numpydoc processing.  See
         `numpydoc issue #130 <https://github.com/numpy/numpydoc/issues/130>`_
 
-14. **Examples**
+.. highlight:: pycon
+
+15. **Examples**
 
     An optional section for examples, using the `doctest
     <http://docs.python.org/library/doctest.html>`_ format.
@@ -413,6 +425,14 @@ The sections of a function's docstring are:
       >>> np.add([1, 2], [3, 4])
       array([4, 6])
 
+    The example code may be split across multiple lines, with each line after
+    the first starting with '... '::
+
+      >>> np.add([[1, 2], [3, 4]],
+      ...        [[5, 6], [7, 8]])
+      array([[ 6,  8],
+             [10, 12]])
+
     For tests with a result that is random or platform-dependent, mark the
     output as such::
 
@@ -456,6 +476,7 @@ The sections of a function's docstring are:
     `matplotlib.sphinxext.plot_directive` is loaded as a Sphinx extension in
     ``conf.py``.
 
+.. highlight:: rst
 
 Documenting classes
 -------------------
@@ -493,7 +514,9 @@ In general, it is not necessary to list class methods.  Those that are
 not part of the public API have names that start with an underscore.
 In some cases, however, a class may have a great many methods, of
 which only a few are relevant (e.g., subclasses of ndarray).  Then, it
-becomes useful to have an additional **Methods** section::
+becomes useful to have an additional **Methods** section:
+
+.. code-block:: python
 
   class Photo(ndarray):
       """

doc/index.rst

@@ -11,7 +11,7 @@ Sphinx, and adds the code description directives ``np:function``,
 ``np-c:function``, etc.  that support the Numpy docstring syntax.
 
 - Development: https://github.com/numpy/numpydoc/
-- Documentation: https://numpydoc.readthedocs.org/
+- Documentation: https://numpydoc.readthedocs.io/
 - PyPI: https://pypi.python.org/pypi/numpydoc/
 
 
@@ -22,3 +22,4 @@ Documentation
     install
     format
     example
+    validation

doc/validation.rst

@@ -0,0 +1,12 @@
+==============================
+Validating NumpyDoc docstrings
+==============================
+
+One tool for validating docstrings is to see how an object's dosctring
+translates to Restructured Text.  Using numpydoc as a command-line tool
+facilitates this. For example to see the Restructured Text generated
+for ``numpy.ndarray``, use:
+
+.. code-block:: bash
+
+    $ python -m numpydoc numpy.ndarray

numpydoc/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import division, absolute_import, print_function
 
-__version__ = '0.8.0.dev0'
+__version__ = '0.9.0.dev0'
 
 
 def setup(app, *args, **kwargs):

numpydoc/__main__.py

@@ -0,0 +1,44 @@
+import argparse
+import importlib
+import ast
+
+from .docscrape_sphinx import get_doc_object
+
+
+def main(argv=None):
+    """Test numpydoc docstring generation for a given object"""
+
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument('import_path', help='e.g. numpy.ndarray')
+
+    def _parse_config(s):
+        key, _, value = s.partition('=')
+        value = ast.literal_eval(value)
+        return key, value
+
+    ap.add_argument('-c', '--config', type=_parse_config,
+                    action='append',
+                    help='key=val where val will be parsed by literal_eval, '
+                         'e.g. -c use_plots=True. Multiple -c can be used.')
+    args = ap.parse_args(argv)
+
+    parts = args.import_path.split('.')
+
+    for split_point in range(len(parts), 0, -1):
+        try:
+            path = '.'.join(parts[:split_point])
+            obj = importlib.import_module(path)
+        except ImportError:
+            continue
+        break
+    else:
+        raise ImportError('Could not resolve {!r} to an importable object'
+                          ''.format(args.import_path))
+
+    for part in parts[split_point:]:
+        obj = getattr(obj, part)
+
+    print(get_doc_object(obj, config=dict(args.config or [])))
+
+if __name__ == '__main__':
+    main()