Question

I am trying to create documentation automatically from the code for all the URLs supported by my application. We are using completely client side MVC, hence each URL that is supported is essentially a REST API for the UI. Is there a easy way to generate the documentation from these URLs?

I wrote this small module as of now, but I am looking for better ways then this. I don’t want to re-invent the wheel if something similar already exists.

UPDATE: Note the intent is to provide a public documentation for the consumers of the website, not for internal consumption. In this regard, for each URL we need to document:
– what is the response,
– which parameters are accepted,
– if the URL responds to GET/POST or both, etc.

Certain URLs like (^$) that simply redirect to home page should not be documented, so I will need some exclusion mechanism as well.

from django.core.management.base import BaseCommand
from django.conf import settings


class Command(BaseCommand):
''' Generates documentation for the URLs.  For each URL includes the documentation from
the callback implementing the URL and prints the default arguments along with the URL pattern and name'''

    def handle(self, *args, **options):
        url_module = None
        exec 'import '+settings.ROOT_URLCONF+'; url_module='+settings.ROOT_URLCONF
        doc = file('doc.html','w')
        doc.write("<table border=1 cellspacing=0 cellpadding=5>")
        doc.write("<tr><th>URL Pattern<th>Name<th>Documentation<th>Parameters")
        for x in url_module.urlpatterns:
            doc.write("<tr>")
            doc.write("<td>")
            doc.write(x._regex)
            doc.write("<td>")
            doc.write(str(x.name))
            try:
                documentation = str(x.callback.__doc__)
                doc.write("<td><pre>")
                doc.write(documentation)
                doc.write("</pre>")
            except:
                doc.write("<td> Unable to find module")
            doc.write("<td>")
            doc.write(str(x.default_args))
        doc.write("</table>")
        doc.close()

Answer 1

Just a Final Update in case anyone is interested.

We ended up using the code snippet I have for internal purposes. We have decided to venture into Sphinx and use that, when we are creating the developer guide at the end of the project, when we are ready for public beta, since it requires some time and investment for learning, logistics etc.