Updated README

Author: Arnaud Coomans

README.md

@@ -1,8 +1,7 @@
 Flask-Autodoc
 =============
 
-Flask Autodoc is a Flask extension that automatically creates documentation for your endpoints based on the routes,
-function arguments and docstring.
+Flask-Autodoc is a Flask extension that automatically creates documentation for your endpoints based on the routes, function arguments and docstrings.
 
 [![Build](https://api.travis-ci.org/acoomans/flask-autodoc.png)](https://travis-ci.org/acoomans/flask-autodoc)
 [![Pypi version](http://img.shields.io/pypi/v/flask-autodoc.svg)](https://pypi.python.org/pypi/Flask-Autodoc)
@@ -13,7 +12,7 @@ function arguments and docstring.
 
 ## Requirements
 
-Flask Autodoc is compatible with Python versions 2 and 3; and depends only on Flask.
+Flask-Autodoc is compatible with Python versions 2 and 3; and it depends only on Flask.
 
 ## Install
 
@@ -35,28 +34,28 @@ Start using Flask-Autodoc by importing it and initializing it:
     app = Flask(__name__)
     auto = Autodoc(app)
 
-by default, Flask-Autodoc will only document the routes you explicitly tell him to with the _doc_ decorator,
-like this:
+by default, Flask-Autodoc will only document the routes explicitly decorated with _doc_:
 
     @app.route('/user/<int:id>')
     @auto.doc()
     def show_user(id):
-        """This returns a user with a given id."""
         return user_from_database(id)
 
-to generate the documentation from an endpoint, use the _html()_ method:
+to generate the documentation, use the _html()_ method:
 
     @app.route('/documentation')
     def documentation():
         return auto.html()
 
-if you to access the documentation without it being rendered in html:
+## Custom documentation
+
+To access the documentation without rendering html:
 
     @app.route('/documentation')
     def documentation():
         return auto.generate()
 
-the documentation will then be returned as a list of rules, where each rule is a dictionary containing:
+the documentation will be returned as a list of rules, where each rule is a dictionary containing:
 
 - methods: the set of allowed methods (ie ['GET', 'POST'])
 - rule: relative url (ie '/user/<int:id>')
@@ -65,34 +64,55 @@ the documentation will then be returned as a list of rules, where each rule is a
 - args: function arguments
 - defaults: defaults values for the arguments
 
-## Groups
+## Custom template
+
+To use a custom template for your documentation, give a _template_ argument to the _html_ method. This will use a template from the flask _templates_ directory. 
+
+Additionnal arguments (other than _group_, _groups_, and _template_) will be passed down to the template:
+
+	auto.html(
+		
+		template='custom_documentation.html'
+		
+		title='My Documentation',
+		author='John Doe',
+	)
+	
+
+_title_ and _author_ will be available in the template:
 
-You may want to group endpoints together, to have different documentation sets. With this you can for example, only
-show some endpoints to third party developer and have full documentation for your own.
+	<!-- templates/custom_documentation.html -->
+	...
+	{% if title is defined %}
+		{{title}}
+	{% endif %}
+	...
 
-to assign an endpoint to a group, pass the name of the group as argument of the _doc_ decorator:
+## Documentation sets
+
+Endpoints can be grouped together in different documentation sets. It is possible for instance to show some endpoints to third party developers and have full documentation for primary developers.
+
+To assign an endpoint to a group, pass the name of the group as argument of the _doc_ decorator:
 
     @app.route('/user/<int:id>')
-    @auto.doc("public")
+    @auto.doc('public')
     def show_user(id):
 
 to assign an endpoint to multiple groups, pass a list of group names as the _groups_ argument to _doc_:
 
     @app.route('/user/<int:id>')
-    @auto.doc(groups=["public","private"])
+    @auto.doc(groups=['public','private'])
     def show_user(id):
 
-to generate the documentation for a specific group, pass the name of the group to the _generate_ or _html_ methods:
-
-    auto.generate("public")
-
-or
-
-    auto.html("public")
+to generate the documentation for a specific group, pass the name of the group to the _html_ or _generate_ methods:
 
+    auto.html('public')
+    auto.html(groups=['public','private'])
+    auto.generate('public')
+    
 ## Examples
 
-Apps in the _examples_ directory mock a blog.
+Apps in the _examples_ directory are an api for a blog:
 
 - _simple_ is a simple app
 - _factory_ uses blueprints