@@ -7,6 +7,8 @@ Changelog
 * Added `Repo.merge_base()` implementation. See the `respective issue on github <https://github.com/gitpython-developers/GitPython/issues/169>`_
 * `[include]` sections in git configuration files are now respected
 * Added `GitConfigParser.rename_section()`
+* DOCS: special members like `__init__` are now listed in the API documentation
+* DOCS: tutorial section was revised entirely
 * Added `Submodule.rename()`
 * **POSSIBLY BREAKING CHANGE**: As `rev_parse` will now throw `BadName` as well as `BadObject`, client code will have to catch both exception types.
 * A list of all issues can be found here: https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v0.3.6+-+Features%22+
 
@@ -8,7 +8,8 @@ Objects.Base
 
 .. automodule:: git.objects.base
    :members:
-   :undoc-members:  
+   :undoc-members:
+   :special-members:
 
 Objects.Blob
 ------------
 
@@ -8,42 +8,54 @@
 GitPython Tutorial
 ==================
 
-GitPython provides object model access to your git repository. This tutorial is  composed of multiple sections, each of which explains a real-life usecase.
+GitPython provides object model access to your git repository. This tutorial is composed of multiple sections, each of which explains a real-life usecase.
 
-Initialize a Repo object
-************************
+Meet the Repo type
+******************
 
-The first step is to create a ``Repo`` object to represent your repository::
+The first step is to create a :class:`git.Repo <git.repo.base.Repo>` object to represent your repository.
 
-    from git import *
-    repo = Repo("/Users/mtrier/Development/git-python")
-    assert repo.bare == False
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: def test_init_repo_object
+    :end-before: # ![1-test_init_repo_object]
 
-In the above example, the directory ``/Users/mtrier/Development/git-python`` is my working repository and contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository::
+In the above example, the directory ``self.rorepo.working_tree_dir`` equals ``/Users/mtrier/Development/git-python`` and is my working repository which contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository.
 
-    repo = Repo.init("/var/git/git-python.git", bare=True)
-    assert repo.bare == True
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: # [2-test_init_repo_object]
+    :end-before: # ![2-test_init_repo_object]
 
-A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the  repository::
+A repo object provides high-level access to your data, it allows you to create and delete heads, tags and remotes and access the configuration of the repository.
 
-    repo.config_reader()        # get a config reader for read-only access
-    repo.config_writer()        # get a config writer to change configuration 
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: # [3-test_init_repo_object]
+    :end-before: # ![3-test_init_repo_object]
 
-Query the active branch, query untracked files or whether the repository data  has been modified::
+Query the active branch, query untracked files or whether the repository data has been modified.
 
-    repo.is_dirty()
-    False
-    repo.untracked_files
-    ['my_untracked_file']
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: # [4-test_init_repo_object]
+    :end-before: # ![4-test_init_repo_object]
 
-Clone from existing repositories or initialize new empty ones::
+Clone from existing repositories or initialize new empty ones.
 
-    cloned_repo = repo.clone("to/this/path")
-    new_repo = Repo.init("path/for/new/repo")
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: # [5-test_init_repo_object]
+    :end-before: # ![5-test_init_repo_object]
 
-Archive the repository contents to a tar file::
+Archive the repository contents to a tar file.
+
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: # [6-test_init_repo_object]
+    :end-before: # ![6-test_init_repo_object]
 
-    repo.archive(open("repo.tar",'w'))
+.. todo repo paths, heads, remotes, submodules
     
     
 Object Databases
@@ -418,16 +430,12 @@ The previous approach would brutally overwrite the user's changes in the working
 Initializing a repository
 *************************
 
-In this example, we will initialize an empty repository, add an empty file to the index, and commit the change::
-
-    repo_dir = 'my-new-repo'
-    file_name = os.path.join(repo_dir, 'new-file')
+In this example, we will initialize an empty repository, add an empty file to the index, and commit the change.
 
-    r = git.Repo.init(repo_dir)
-    # This function just creates an empty file ... 
-    touch(file_name)
-    r.index.add([file_name])
-    r.index.commit("initial commit")
+.. literalinclude:: ../../git/test/test_docs.py
+    :language: python
+    :start-after: def test_add_file_and_commit
+    :end-before: # ![test_add_file_and_commit]
 
 Please have a look at the individual methods as they usually support a vast amount of arguments to customize their behavior.
 
 
@@ -295,7 +295,7 @@ def wait(self):
             :raise GitCommandError: if the return status is not 0"""
             status = self.proc.wait()
             if status != 0:
-                raise GitCommandError(self.args, status, self.proc.stderr.read().decode(defenc))
+                raise GitCommandError(self.args, status, self.proc.stderr.read())
             # END status handling
             return status
     # END auto interrupt
 
@@ -132,9 +132,11 @@ class IndexObject(Object):
 
     def __init__(self, repo, binsha, mode=None, path=None):
         """Initialize a newly instanced IndexObject
+
         :param repo: is the Repo we are located in
         :param binsha: 20 byte sha1
-        :param mode: is the stat compatible file mode as int, use the stat module
+        :param mode: 
+            is the stat compatible file mode as int, use the stat module
             to evaluate the infomration
         :param path:
             is the path to the file in the file system, relative to the git repository root, i.e.
@@ -149,7 +151,8 @@ def __init__(self, repo, binsha, mode=None, path=None):
             self.path = path
 
     def __hash__(self):
-        """:return:
+        """
+        :return:
             Hash of our path as index items are uniquely identifyable by path, not
             by their data !"""
         return hash(self.path)
 
@@ -6,21 +6,62 @@
 # the BSD License: http://www.opensource.org/licenses/bsd-license.php
 import os
 
-import git
 from git.test.lib import TestBase
 from gitdb.test.lib import with_rw_directory
-from git.repo.fun import touch
 
 
-class TestGit(TestBase):
+class Tutorials(TestBase):
+
+    @with_rw_directory
+    def test_init_repo_object(self, rw_dir):
+        from git import Repo
+        join = os.path.join
+
+        # rorepo is a a Repo instance pointing to the git-python repository.
+        # For all you know, the first argument to Repo is a path to the repository
+        # you want to work with
+        repo = Repo(self.rorepo.working_tree_dir)
+        assert repo.bare == False
+        # ![1-test_init_repo_object]
+
+        # [2-test_init_repo_object]
+        bare_empty_repo = Repo.init(join(rw_dir, 'bare-repo'), bare=True)
+        assert bare_empty_repo.bare == True
+        # ![2-test_init_repo_object]
+        
+        # [3-test_init_repo_object]
+        repo.config_reader()             # get a config reader for read-only access
+        cw = repo.config_writer()        # get a config writer to change configuration
+        cw.release()                     # call release() to be sure changes are written and locks are released
+        # ![3-test_init_repo_object]
+
+        # [4-test_init_repo_object]
+        repo.is_dirty()
+        # False
+        repo.untracked_files
+        # ['my_untracked_file']
+        # ![4-test_init_repo_object]
+        
+        # [5-test_init_repo_object]
+        assert repo.clone(join(rw_dir, 'to/this/path')).__class__ is Repo
+        assert Repo.init(join(rw_dir, 'path/for/new/repo')).__class__ is Repo
+        # ![5-test_init_repo_object]
+        
+        # [6-test_init_repo_object]
+        repo.archive(open(join(rw_dir, 'repo.tar'), 'w'))
+        # ![6-test_init_repo_object]
 
     @with_rw_directory
     def test_add_file_and_commit(self, rw_dir):
+        import git
+
         repo_dir = os.path.join(rw_dir, 'my-new-repo')
         file_name = os.path.join(repo_dir, 'new-file')
 
         r = git.Repo.init(repo_dir)
         # This function just creates an empty file ...
-        touch(file_name)
+        open(file_name, 'wb').close()
         r.index.add([file_name])
         r.index.commit("initial commit")
+
+        # ![test_add_file_and_commit]
@@ -783,7 +783,7 @@ def test_branch_renames(self, rw_dir):
         # Setup initial sandbox:
         # parent repo has one submodule, which has all the latest changes
         source_url = self._submodule_url()
-        sm_source_repo = git.Repo.clone_from(source_url, os.path.join(rw_dir, 'sm-source'))
+        sm_source_repo = git.Repo.clone_from(source_url, os.path.join(rw_dir, 'sm-source'), b='master')
         parent_repo = git.Repo.init(os.path.join(rw_dir, 'parent'))
         sm = parent_repo.create_submodule('mysubmodule', 'subdir/submodule',
                                           sm_source_repo.working_tree_dir, branch='master')