Opened 11 years ago

Closed 9 years ago

#1248 closed enhancement (wontfix)

[patch] API Reference

Reported by: linicks@… Owned by: jacob
Component: Documentation Version:
Severity: minor Keywords: API Reference
Cc: django@… Triage Stage: Design decision needed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:


The online docs are great, but an organized API Reference would be very useful. One popular generator is Epydoc (

Attachments (2)

api_css.diff (8.5 KB) - added by django@… 10 years ago.
epydoc css file that generates a django styled api doc (295 bytes) - added by django@… 10 years ago.
my update script to keep uptodate

Download all attachments as: .zip

Change History (10)

comment:1 Changed 11 years ago by django@…

I had the idea last week too, but was to busy investigeting doc generators :)
Epydoc looks nice, but there is a bug that causes to abort the script. django.utils.html uses unicode character that caused the script to abort.
I prepared a fix in

However, the docs generated by epydoc are very incomplete. I will try synopsis now, which i used in other projects very succesfully. The program design is much more advanced and allows very good customization.

Changed 10 years ago by django@…

epydoc css file that generates a django styled api doc

comment:2 Changed 10 years ago by django@…

  • Summary changed from API Reference to [patch] API Reference

The css requires Epydoc 3.0alpha, old versions have problems because they use introspection, which doesn't work of the python magic involved :)

to generate the doc i use this command:

epydoc -odocs/api django --verbose --parse-only --name="Django API" --url= --show-imports --css=docs/api.css

I don't know much about setup tools, but a command " makedoc" or such would be nice. Also[trunk|branch|...] would be very nice. The script could be run through a svn on commit command.

comment:3 Changed 10 years ago by django@…

  • Cc django@… added

Changed 10 years ago by django@…

my update script to keep uptodate

comment:4 Changed 10 years ago by Julien Poissonnier <poissonnier@…>

Apparently it is possible to have links to colorized source code from within the documentation, however I couldn't find these. I guess there is a commandline flag to enable the code listings, would it be possible to turn that on?

comment:5 Changed 10 years ago by django@…

I know. It worked with the alpha release, but i now run trunk of epydoc and the option somehow doesn't work anymore. I havn't looked into it yet, but i had to pull trunk, because the releas had other problems :)

comment:6 Changed 10 years ago by adrian

  • priority changed from normal to low
  • Severity changed from normal to minor

comment:7 Changed 10 years ago by SmileyChris

  • Triage Stage changed from Unreviewed to Design decision needed

comment:8 Changed 9 years ago by jacob

  • Resolution set to wontfix
  • Status changed from new to closed

IMO (and in that of most of the Django developers I've talked to), automatically generated API documentation is -- at best -- a poor excuse for not having real docs. I'd rather spend my time writing real docs, and I'd prefer the community do the same.

Thus, I'm marking this WONTFIX.

If anyone's reading this and gets pissed, here are the circumstances under which I'd consider adding an automatically generated API doc somewhere on the site. I'd only consider a tool that:

  • Is easily customizable (i.e. uses some sort of same template for the output).
  • Doesn't use frames (seriously).
  • Has some sort of commenting or wiki-like functionality to allow the community to annotate APIs.

If anyone knows of such a tool then let me know.

Note: See TracTickets for help on using tickets.
Back to Top