Merge pull request #19 from Chilipp/unify-methods

Unify methods of the DocstringProcessor

.travis.yml

@@ -5,6 +5,7 @@ python:
   - "3.5"
   - "3.6"
   - "3.7"
+  - "3.8"
 dist: xenial
 install:
   - pip install coveralls pytest

CHANGELOG.rst

@@ -1,3 +1,51 @@
+v0.3.0
+======
+New framework for decorators, see PR `#19 <https://github.com/Chilipp/docrep/pull/19>`__
+
+This release deprecates several methods of the :class:`DocstringProcessor` in
+favor of a more uniform framework. Functions such as `get_sections` and `dedent`
+now work for both, as decorators and directly on strings. See
+:ref:`migrate-to-0.3` down below
+
+.. _changed-in-0.3:
+
+Changed
+-------
+- The following methods of the :class:`DocstringProcessor` class have been
+  deprecated:
+
+  docstring update methods for strings:
+    * ``dedents`` in favor of :meth:`~DocstringProcessor.dedent`
+    * ``with_indents`` in favor of :meth:`~DocstringProcessor.with_indent`
+  docstring analysis decorators
+    * ``get_sectionsf`` in favor of :meth:`~DocstringProcessor.get_sections`
+    * ``get_summaryf`` in favor of :meth:`~DocstringProcessor.get_summary`
+    * ``get_full_descriptionf`` in favor of :meth:`~DocstringProcessor.get_full_description`
+    * ``get_extended_summaryf`` in favor of :meth:`~DocstringProcessor.get_extended_summary`
+    * ``save_docstring`` in favor of :meth:`~DocstringProcessorget_docstring`
+  docstring parameter and type extractors for strings
+    * ``delete_params_s`` in favor of :func:`docrep.delete_params`
+    * ``delete_types_s`` in favor of :func:`docrep.delete_types`
+    * ``delete_kwargs_s`` in favor of :func:`docrep.delete_kwargs`
+    * ``keep_params_s`` in favor of :func:`docrep.keep_params`
+    * ``keep_types_s`` in favor of :func:`docrep.keep_types`
+
+.. _migrate-to-0.3:
+
+Migrating from 0.2.8 to 0.3.0
+-----------------------------
+Migration is possible using the following steps:
+
+* For the deprecated update methods (see the :ref:`changes above <changed-in-0.3>`),
+  just use the above-mentioned replacement. They work for both, as decorators and
+  with strings.
+* For the analysis decorators (``get_sectionsf`` for instance, use the replacement)
+  but you need to explicitly state the `base` parameter.
+  ``@get_sectionsf('something')`` for instance needs to be replaced with
+  ``@get_sections(base='something')``
+* for the parameter and type extractor functions, just use the corresponding
+  module level function mentioned :ref:`above <changed-in-0.3>`
+
 v0.2.8
 ======
 Minor patch to solve deprecation warnings for various regular expressions.