From 7e3f6d41d72820ef57121e7b9fdb03f98515f661 Mon Sep 17 00:00:00 2001
From: Joshua Harlow <harlowja@yahoo-inc.com>
Date: Fri, 6 Feb 2015 18:32:45 -0800
Subject: [PATCH] Add doctested examples into the documentation
To make it more easy for those to see how to use
this library, start adding some basic examples that
show the common usage patterns.
Change-Id: Ieda04d0c3402cb3d9d7e55ecfd737571520ffbcb
---
doc/source/conf.py | 1 +
doc/source/examples.rst | 173 ++++++++++++++++++++++++++++++++++++++++
doc/source/index.rst | 1 +
3 files changed, 175 insertions(+)
create mode 100644 doc/source/examples.rst
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 0c18ec9..17d8e70 100644
--- a/doc/source/conf.py
+++ b/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',
]
diff --git a/doc/source/examples.rst b/doc/source/examples.rst
new file mode 100644
index 0000000..35e39a0
--- /dev/null
+++ b/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
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 947d0e1..ce2282a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -18,6 +18,7 @@ Contents
installation
api
+ examples
contributing
Indices and tables