Question

I have a Django website and I created a REST api. In the view functions I have documentation on the REST urls and I want to generate API docs for the REST urls. The view functions look like this:

def genres(request):
    """
    Url: /api/genres/
    Parameters: None
    Returns: list of genres { { "id":1, "name":"action" }, {...} }
    """
    pass

But when I run sphinx on myproject.api.views I get html docs for calling the api in python. Is there a way to configure sphinx to document it like a REST api?

Or am I better off writing a script to generate my docs from the docstrings myself?

Answer 1

Check sphinxcontrib-httpdomain

You can use autodoc in order to use the docstrings and the httpdomain extension in order to use .. http:get:: /users/ style directives. This solution has a problem, it will also show the functions’ signatures. In order to get around the problem, I tinkered a bit with the Sphinx source code, making a copy of the original autodoc extension that wouldn’t add the signatures to the final documentation.

The files can be found on https://gist.github.com/4589457

Instructions:

1. Replace application.py on sphinx path with the one on the gist (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/)
2. Add simpleautodoc.py on the ext folder
3. Add the httpdomain extension on conf.py in order to use .. http:get:: /users/ style directives
4. Use simpleautodoc as you would use autodoc using the prefix autosimple instead of auto (eg autosimplemodule instead of automodule autosimpleclass instead of autoclass etc)
5. The example.py file shows a sample of how I format the docstrings