From c64529065f70f3db7a16637f77bd9cc3a5f9486c Mon Sep 17 00:00:00 2001
From: Christian Herdtweck <christian.herdtweck@intra2net.com>
Date: Thu, 20 Aug 2015 16:05:50 +0200
Subject: [PATCH] added some examples for documentation of param and return values and links to template

---
 doc/conf.py |    2 +-
 template.py |   49 +++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 48 insertions(+), 3 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index 875c9d0..04635e9 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -293,7 +293,7 @@ texinfo_documents = [
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {'https://docs.python.org/3.3': None}
 
 # show doc of class AND of constructor
 autoclass_content = 'class'  # 'both' not needed if special-members is used
diff --git a/template.py b/template.py
index 11e990f..090bb82 100644
--- a/template.py
+++ b/template.py
@@ -21,7 +21,11 @@
 """
 Module name: Summary of this module
 
-Details on what happens here should be specified here but please keep it brief!
+Some overview over important classes and functions and such should be specified
+in this docstring, but please keep it brief!
+
+Do not forget to correct the codeauthor and license text commented by hashes
+above.
 
 .. codeauthor:: John Doe, john.doe@intra2net.com
 """
@@ -33,10 +37,51 @@ class TestClass:
 
     does nothing, really
     """
-    pass
+
+    def __init__(self, args):
+        """ constructor, gets its own paragraph in documentation
+
+        :raises NotImplementedError: always
+        """
+        raise NotImplementedError()
+
+    def test_method(self, arg):
+        """ test method, does nothing
+
+        for more doc string examples, see function :py:func:`send_message`
+
+        :param arg: some argument
+        :return: Nothing
+        :raises NotImplementedError: always
+        """
+        raise NotImplementedError()
 # end: class TestClass
 
 
+def send_message(sender, recipient, message_body, priority=1):
+    """ Send a message to a recipient
+
+    Example for a docstring that uses lots of reST fields, taken from
+    http://sphinx-doc.org/domains.html
+
+    Does not use :py:class:`TestClass` at all. Also has nothing to do with
+    the python module :py:mod:`logging.handlers`
+
+    :param str sender: The person sending the message
+    :param str recipient: The recipient of the message
+    :param str message_body: The body of the message
+    :param priority: The priority of the message, can be a number 1-5
+    :type priority: integer or None
+    :return: the message id
+    :rtype: int
+    :raises ValueError: if the message_body exceeds 160 characters
+    :raises TypeError: if the message_body is not a basestring
+    :raises NotImplementedError: always
+    """
+
+    raise NotImplementedError()
+
+
 def main():
     """ Main function, called when running file as script
 
-- 
1.7.1