Python 3 support and a more interactive doc page

[hospadar]

This adds a more interactive documentation page, with such exciting features as:

• collapsible sections
• the ability to try REST calls on the page and see the response (similar to a swagger-ui like this: http://petstore.swagger.wordnik.com/)
• python 3 support
• The ability to document query string args by adding some parameters to the decorator
• A little colorizing and borderizing to make long docs a little more readable

[acoomans]

Hi Luke, Thanks for your pull request, this is amazing work.

The python 3, pep8 clean ups and fixes are really appreciated.

The template is really great as well. However, I do want to keep the default template as simple as possible. Autodoc has a way to use a custom template from your project with the template argument in both html() and generate(). It's true that feature, while documented in autodoc.py, was not mentioned in the README though. As I think your work is valuable, I propose to move your template in an example if you don't mind. See 7ebaa5d47a08f3c169a03e4999b310fc91ecee02 .

Regarding the query string parameter (and also POST form data by the way), I am undecided for now. I believe this can be documented within the docstring. But I might change my mind if there are enough requests.

Thanks, -- Arnaud

[hospadar]

Totally understand wanting to keep the default template simple - as to the query string parameters, my initial thought was to use them to generate a form to build up the URL, but I decided to bail on that to keep the complexity relatively small.

As it stands, I'm not particularly attached to the query string params and I think just documenting them in the docstring is probably fine.

One other think I'm thinking about adding is to render the docstring with markdown or something. Not sure exactly how that's going to play with the indentation of docstrings, still need to do some investigation there.

Maybe I'll try a branch with the template arranged as a separate custom template (as in 7ebaa5 ), the query params removed (since I'm not really using them), and markdown rendering (if I can get that to work cleanly)?

[hospadar]

Ok, new stuff:

I added the interactive template to the templates directory so although it's not the default, it can be used easily by just using it's name when html is called.

Also added the reStructuredText support from the rst branch for my own usage, if you don't want that yet, you could just revert 75a16e6 before merging.

Also removed the query parameter support from my branch since I'm not even using it. Maybe I'll add it back in later if I come across a need and want to build the interactive template into more of a url-building form.

[lukeyeager]

@hospadar, I haven't looked at this in depth, but it looks like some of this has been merged already. Would you still like to contribute any of this, or shall I close this PR?