How to generate web API docs from python docstrings

March 26th, 2013 § Leave a Comment

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

Replace application.py

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

Use simpleautodoc

as you would use autodoc using the prefix autosimple instead of auto (eg autosimplemodule instead of automodule autosimpleclass instead of autoclass etc)

Example

The file below shows a sample of how I format the docstrings

Leave a Reply

What’s this?

You are currently reading How to generate web API docs from python docstrings at Utopian Labs Blog.

meta

%d bloggers like this: