Opened 11 years ago

Closed 10 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:

Description

The online docs are great, but an organized API Reference would be very useful. One popular generator is Epydoc (http://epydoc.sourceforge.net/).

Attachments (2)

api_css.diff (8.5 KB) - added by django@… 11 years ago.
epydoc css file that generates a django styled api doc
update.sh (295 bytes) - added by django@… 11 years ago.
my update script to keep http://djangoapi.quamquam.org 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
http://sourceforge.net/tracker/index.php?func=detail&aid=780172&group_id=32455&atid=405618

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 11 years ago by django@…

Attachment: api_css.diff added

epydoc css file that generates a django styled api doc

comment:2 Changed 11 years ago by django@…

Summary: API Reference [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=http://www.djangoproject.com --show-imports --css=docs/api.css

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

comment:3 Changed 11 years ago by django@…

Cc: django@… added

Changed 11 years ago by django@…

Attachment: update.sh added

my update script to keep http://djangoapi.quamquam.org uptodate

comment:4 Changed 11 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 11 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 Holovaty

priority: normallow
Severity: normalminor

comment:7 Changed 10 years ago by Chris Beaven

Triage Stage: UnreviewedDesign decision needed

comment:8 Changed 10 years ago by Jacob

Resolution: wontfix
Status: newclosed

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