I've developed a small RESTful service with Tornado and I wanted to generated doc for the exposed API. Lucky me, someone already thought about it and created the sphinxcontrib.autohttp.tornado addon for Sphinx.
The next few tips will help getting the work done:
- If you're using python-3, you need to use this file tornado.py. The latest release 1.2.1 (as of 30/04/2014) doesn't work with python-3, because
methods = inspect.getmembers(handler, predicate=inspect.ismethod) # returns an empty array with python-3
The predicate needs to be changed to include ismethod or isfunction
- In the subclass of the RequestHandler, be sure that the SUPPORTED_METHODS is defined as a tuple
SUPPORTED_METHODS=('GET') # WRONG SUPPORTED_METHODS=('GET',) # CORRECT
- If you add a decorator to your handler methodes, be sure to use functools.wraps or functools.update_wrapper to copy the docstring of the original method to the function returned by the decorator.