Merge pull request #11 from Chilipp/dev

New version with improved docstrings and python 3.7 support

.travis.yml

@@ -4,6 +4,8 @@ python:
   - "3.4"
   - "3.5"
   - "3.6"
+  - "3.7"
+dist: xenial
 install:
   - pip install coveralls pytest
   - python setup.py install

CHANGELOG.rst

@@ -1,3 +1,9 @@
+v0.2.4
+======
+This new minor release has an improved documentation considering the
+``keep_params`` and ``keep_types`` section and triggers new builds for python
+3.7.
+
 v0.2.3
 ======
 This minor release contains some backward incompatible changes on how to handle

docrep/__init__.py

@@ -5,7 +5,7 @@
 from warnings import warn
 
 
-__version__ = '0.2.3'
+__version__ = '0.2.4'
 
 __author__ = 'Philipp Sommer'
 
@@ -207,7 +207,6 @@ class DocstringProcessor(object):
         ...     %(not_dedented.parameters)s'''
         ...     pass
 
-
     """
 
     #: :class:`dict`. Dictionary containing the compiled patterns to identify
@@ -474,6 +473,12 @@ def delete_params(self, base_key, *params):
         documentation without the description of the param. This method works
         for the ``'Parameters'`` sections.
 
+        The new docstring without the selected parts will be accessible as
+        ``base_key + '.no_' + '|'.join(params)``, e.g.
+        ``'original_key.no_param1|param2'``.
+
+        See the :meth:`keep_params` method for an example.
+
         Parameters
         ----------
         base_key: str
@@ -484,7 +489,7 @@ def delete_params(self, base_key, *params):
 
         See Also
         --------
-        delete_types"""
+        delete_types, keep_params"""
         self.params[
             base_key + '.no_' + '|'.join(params)] = self.delete_params_s(
                 self.params[base_key], params)
@@ -590,6 +595,9 @@ def delete_types(self, base_key, out_key, *types):
         documentation without the description of the param. This method works
         for ``'Results'`` like sections.
 
+
+        See the :meth:`keep_types` method for an example.
+
         Parameters
         ----------
         base_key: str
@@ -639,6 +647,10 @@ def keep_params(self, base_key, *params):
         documentation with only the description of the param. This method works
         for ``'Parameters'`` like sections.
 
+        The new docstring with the selected parts will be accessible as
+        ``base_key + '.' + '|'.join(params)``, e.g.
+        ``'original_key.param1|param2'``
+
         Parameters
         ----------
         base_key: str
@@ -649,7 +661,68 @@ def keep_params(self, base_key, *params):
 
         See Also
         --------
-        keep_types"""
+        keep_types, delete_params
+
+        Examples
+        --------
+        To extract just two parameters from a function and reuse their
+        docstrings, you can type::
+
+            >>> from docrep import DocstringProcessor
+            >>> d = DocstringProcessor()
+            >>> @d.get_sectionsf('do_something')
+            ... def do_something(a=1, b=2, c=3):
+            ...     '''
+            ...     That's %(doc_key)s
+            ...
+            ...     Parameters
+            ...     ----------
+            ...     a: int, optional
+            ...         A dummy parameter description
+            ...     b: int, optional
+            ...         A second dummy parameter that will be excluded
+            ...     c: float, optional
+            ...         A third parameter'''
+            ...     print(a)
+
+            >>> d.keep_params('do_something.parameters', 'a', 'c')
+
+            >>> @d.dedent
+            ... def do_less(a=1, c=4):
+            ...     '''
+            ...     My second function with only `a` and `c`
+            ...
+            ...     Parameters
+            ...     ----------
+            ...     %(do_something.parameters.a|c)s'''
+            ...     pass
+
+            >>> print(do_less.__doc__)
+            My second function with only `a` and `c`
+            <BLANKLINE>
+            Parameters
+            ----------
+            a: int, optional
+                A dummy parameter description
+            c: float, optional
+                A third parameter
+
+        Equivalently, you can use the :meth:`delete_params` method to remove
+        parameters::
+
+            >>> d.delete_params('do_something.parameters', 'b')
+
+            >>> @d.dedent
+            ... def do_less(a=1, c=4):
+            ...     '''
+            ...     My second function with only `a` and `c`
+            ...
+            ...     Parameters
+            ...     ----------
+            ...     %(do_something.parameters.no_b)s'''
+            ...     pass
+
+        """
         self.params[base_key + '.' + '|'.join(params)] = self.keep_params_s(
             self.params[base_key], params)
 
@@ -699,7 +772,63 @@ def keep_types(self, base_key, out_key, *types):
 
         See Also
         --------
-        keep_params"""
+        delete_types, keep_params
+
+        Examples
+        --------
+        To extract just two return arguments from a function and reuse their
+        docstrings, you can type::
+
+            >>> from docrep import DocstringProcessor
+            >>> d = DocstringProcessor()
+            >>> @d.get_sectionsf('do_something', sections=['Returns'])
+            ... def do_something():
+            ...     '''
+            ...     That's %(doc_key)s
+            ...
+            ...     Returns
+            ...     -------
+            ...     float
+            ...         A random number
+            ...     int
+            ...         A random integer'''
+            ...     return 1.0, 4
+
+            >>> d.keep_types('do_something.returns', 'int_only', 'int')
+
+            >>> @d.dedent
+            ... def do_less():
+            ...     '''
+            ...     My second function that only returns an integer
+            ...
+            ...     Returns
+            ...     -------
+            ...     %(do_something.returns.int_only)s'''
+            ...     return do_something()[1]
+
+            >>> print(do_less.__doc__)
+            My second function that only returns an integer
+            <BLANKLINE>
+            Returns
+            -------
+            int
+                A random integer
+
+        Equivalently, you can use the :meth:`delete_types` method to remove
+        parameters::
+
+            >>> d.delete_types('do_something.returns', 'no_float', 'float')
+
+            >>> @d.dedent
+            ... def do_less():
+            ...     '''
+            ...     My second function with only `a` and `c`
+            ...
+            ...     Returns
+            ...     ----------
+            ...     %(do_something.returns.no_float)s'''
+            ...     return do_something()[1]
+        """
         self.params['%s.%s' % (base_key, out_key)] = self.keep_types_s(
             self.params[base_key], types)
 

docs/requirements.txt

@@ -0,0 +1,6 @@
+# Sphinx
+#   https://github.com/sphinx-doc/sphinx/blob/master/CHANGES
+sphinx==1.8.0 # rq.filter: >=1.3, <1.9
+
+# autodocsumm
+autodocsumm==0.1.7 # rq.filter: >= 0.1.6

setup.py

@@ -11,7 +11,7 @@ def readme():
 
 
 setup(name='docrep',
-      version='0.2.3',
+      version='0.2.4',
       description='Python package for docstring repetition',
       long_description=readme(),
       classifiers=[
@@ -25,6 +25,7 @@ def readme():
         'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
         'Programming Language :: Python :: 3.6',
+        'Programming Language :: Python :: 3.7',
         'Operating System :: OS Independent',
       ],
       keywords='docstrings docs docstring napoleon numpy reStructured text',