Merge pull request #12 from acoomans/development

Development

Author: Arnaud Coomans

.travis.yml

@@ -1,6 +1,8 @@
 language: python
 python:
   - "2.7"
+  - "3.3"
+  - "3.4"
 install: 
   - pip install -r requirements.txt
 script: 

README.md

@@ -1,14 +1,26 @@
 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 Status](https://api.travis-ci.org/acoomans/flask-autodoc.png)](https://travis-ci.org/acoomans/flask-autodoc)
+[![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)
+[![Pypi license](http://img.shields.io/pypi/l/flask-autodoc.svg)](https://pypi.python.org/pypi/Flask-Autodoc)
+![Python 2](http://img.shields.io/badge/python-2-blue.svg)
+![Python 3](http://img.shields.io/badge/python-3-blue.svg)
+
+
+## Requirements
+
+Flask-Autodoc is compatible with Python versions 2 and 3; and it depends only on Flask.
 
 ## Install
 
-To install Flask-Autodoc:
+To install Flask-Autodoc, run pip:
+
+	pip install flask-autodoc
+	
+or clone this directory and run setup:
 
     python setup.py install
 
@@ -22,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>')
@@ -52,27 +64,67 @@ 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',
+	)
+	
 
-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.
+_title_ and _author_ will be available in the template:
 
-to assign an endpoint to a group, pass the name of the group as argument of the _doc_ decorator:
+	<!-- templates/custom_documentation.html -->
+	...
+	{% if title is defined %}
+		{{title}}
+	{% endif %}
+	...
+
+## 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:
+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 are an api for a blog:
+
+- _simple_ is a simple app
+- _factory_ uses blueprints
+
+Run with
+
+	python simple/blog.py
+	
+and connect to [/doc/public](http://127.0.0.1:5000/doc/public) and [/doc/private](http://127.0.0.1:5000/doc/private) to see public and private documentations.
 
-    auto.generate("public")
+## Screenshots
 
-or
+![screenshots](Screenshots/screenshot00.png)
 
-    auto.html("public")
+![screenshots](Screenshots/screenshot01.png)

examples/blog.py

@@ -1,5 +1,5 @@
 from flask import Flask
-from flask.ext.autodoc import Autodoc
+
 
 def create_app(config_filename=None):
     app = Flask(__name__)
@@ -18,6 +18,7 @@ def create_app(config_filename=None):
 
     return app
 
-if __name__ == "__main__":
+
+if __name__ == '__main__':
     app = create_app()
-    app.run()
+    app.run()

examples/factory/app.py

@@ -1,3 +1,3 @@
-from admin import admin
-from frontend import frontend
-from doc import doc, auto
+from .admin import admin
+from .frontend import frontend
+from .doc import doc, auto

examples/factory/blog/__init__.py

@@ -1,11 +1,13 @@
-from flask import current_app, Blueprint, render_template
-from flask.ext.autodoc import Autodoc
+from flask import Blueprint
+
+from .doc import auto
+
 
 admin = Blueprint('admin', __name__, url_prefix='/admin')
-from doc import auto
+
 
 @admin.route('/')
 @auto.doc(groups=['private'])
 def index():
     """Admin interface."""
-    return "Admin interface"
+    return 'Admin interface'

examples/factory/blog/admin.py

@@ -1,14 +1,17 @@
-from flask import current_app, Blueprint, render_template
+from flask import Blueprint
 from flask.ext.autodoc import Autodoc
 
+
 doc = Blueprint('doc', __name__, url_prefix='/doc')
 auto = Autodoc()
 
+
 @doc.route('/')
 @doc.route('/public')
 def public_doc():
-    return auto.html(groups=["public"], title="Blog Documentation")
+    return auto.html(groups=['public'], title='Blog Documentation')
+
 
 @doc.route('/private')
 def private_doc():
-    return auto.html(groups=["private"], title="Private Documentation")
+    return auto.html(groups=['private'], title='Private Documentation')