Merge "Add doctested examples into the documentation"

doc/source/conf.py

@@ -24,6 +24,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.viewcode',
+    'sphinx.ext.doctest',
     'oslosphinx',
 ]
 

doc/source/examples.rst

@@ -0,0 +1,173 @@
+========
+Examples
+========
+
+Moving a method
+---------------
+
+To move a *instance* method from an existing one to a new one
+the :py:func:`~debtcollector.moves.moved_method` function/decorator can be
+used to achieve this in a non-destructive manner.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import moves
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> class Cat(object):
+    ...   @moves.moved_method('meow')
+    ...   def mewow(self):
+    ...     return self.meow()
+    ...   def meow(self):
+    ...     return 'kitty'
+    ...
+    >>> c = Cat()
+    >>> c.mewow()
+    __main__:1: DeprecationWarning: Method 'Cat.mewow()' has moved to 'Cat.meow()'
+    'kitty'
+    >>> c.meow()
+    'kitty'
+
+Moving a property
+-----------------
+
+To move a *instance* property from an existing one to a new one
+the :py:func:`~debtcollector.moves.moved_property` function/decorator can be
+used to achieve this in a non-destructive manner.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import moves
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> class Dog(object):
+    ...   @property
+    ...   @moves.moved_property('bark')
+    ...   def burk(self):
+    ...     return self.bark
+    ...   @property
+    ...   def bark(self):
+    ...     return 'woof'
+    ...
+    >>> d = Dog()
+    >>> d.burk
+    __main__:1: DeprecationWarning: Property 'Dog.burk' has moved to 'Dog.bark'
+    'woof'
+    >>> d.bark
+    'woof'
+
+Moving a class
+--------------
+
+To move a *class* from an existing one to a new one
+the :py:func:`~debtcollector.moves.moved_class` type generator function can
+be used to achieve this in a non-destructive manner.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import moves
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> class WizBang(object):
+    ...   pass
+    ...
+    >>> OldWizBang = moves.moved_class(WizBang, 'OldWizBang', __name__)
+    >>> a = OldWizBang()
+    __main__:1: DeprecationWarning: Class '__main__.OldWizBang' has moved to '__main__.WizBang'
+    >>> b = WizBang()
+
+Renaming a keyword argument
+---------------------------
+
+To notify the user when a keyword argument has been replaced with a new and
+improved keyword argument and the user is still using the old keyword argument
+the :py:func:`~debtcollector.renames.renamed_kwarg` function/decorator
+can be used to achieve this in a non-destructive manner.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import renames
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> @renames.renamed_kwarg('snizzle', 'nizzle')
+    ... def do_the_deed(snizzle=True, nizzle=True):
+    ...   print(snizzle)
+    ...   print(nizzle)
+    ...
+    >>> do_the_deed()
+    True
+    True
+    >>> do_the_deed(snizzle=False)
+    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead
+    False
+    True
+    >>> do_the_deed(nizzle=False)
+    True
+    False
+
+Further customizing the emitted messages
+----------------------------------------
+
+It is typically useful to tell the user when a deprecation has started and
+when the deprecated item will be offically removed (deleted or other). To
+enable this all the currently provided functions this library provides
+take a ``message``, ``version`` and ``removal_version`` keyword arguments.
+These are used in forming the message that is shown to the user when they
+trigger the deprecated activity.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import renames
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="0.7")
+    ... def do_the_deed(snizzle=True, nizzle=True):
+    ...   pass
+    ...
+    >>> do_the_deed(snizzle=False)
+    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in version '0.7', please use the 'nizzle' argument instead
+
+If the ``removal_version`` is unknown the special character ``?`` can be used
+instead (to denote that the deprecated activity will be removed sometime in
+the future).
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import renames
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> @renames.renamed_kwarg('snizzle', 'nizzle', version="0.5", removal_version="?")
+    ... def do_the_deed(snizzle=True, nizzle=True):
+    ...   pass
+    ...
+    >>> do_the_deed(snizzle=False)
+    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated in version '0.5' and will be removed in a future version, please use the 'nizzle' argument instead
+
+To further customize the message (with a special postfix) the ``message``
+keyword argument can be provided.
+
+A basic example to do just this:
+
+.. doctest::
+
+    >>> from debtcollector import renames
+    >>> import warnings
+    >>> warnings.simplefilter('always')
+    >>> @renames.renamed_kwarg('snizzle', 'nizzle', message="Pretty please stop using it")
+    ... def do_the_deed(snizzle=True, nizzle=True):
+    ...   pass
+    ...
+    >>> do_the_deed(snizzle=False)
+    __main__:1: DeprecationWarning: Using the 'snizzle' argument is deprecated, please use the 'nizzle' argument instead: Pretty please stop using it

doc/source/index.rst

@@ -18,6 +18,7 @@ Contents
 
    installation
    api
+   examples
    contributing
 
 Indices and tables