How to generate web API docs from python docstrings
This is mostly a post made in order to facilitate the process of communicating to colleagues how to setup their computers in order to have auto-generated documentation for the projects we share, and since I have already given the same answer to a Stack Overflow question, it might be useful to someone else.
We are going to use Sphinx for the documentation and sphinxcontrib-httpdomain extension for our RESTful API. While this extension does provide an auto-generation solution for code written for Flask, the result the code I’ve written for GAE comes out quite awful, documenting the API’s methods as class functions. In order to circumvent this, we need to modify Sphinx code a bit.
Add simpleautodoc.py on the ext folder
On sphinx path with the one below (the path on my system is /Library/Frameworks/Python.framework/Versions/Current/lib/python2.7/site-packages/Sphinx-1.1.3-py2.7.egg/sphinx/)
Add the httpdomain extension on conf.py
in order to use .. http:get:: /users/ style directives
as you would use autodoc using the prefix autosimple instead of auto (eg autosimplemodule instead of automodule autosimpleclass instead of autoclass etc)
The file below shows a sample of how I format the docstrings