diff --git a/.travis.yml b/.travis.yml index 56342ec..137869e 100644 --- a/.travis.yml +++ b/.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 diff --git a/CHANGELOG.rst b/CHANGELOG.rst index f454239..21df96e 100644 --- a/CHANGELOG.rst +++ b/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 diff --git a/docrep/__init__.py b/docrep/__init__.py index 5b6d3e1..15cd3c4 100755 --- a/docrep/__init__.py +++ b/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` + + 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 + + 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) diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b7477d1 --- /dev/null +++ b/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 diff --git a/setup.py b/setup.py index 87651dc..5ad94ac 100644 --- a/setup.py +++ b/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',