Code

Opened 8 years ago

Closed 7 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@… 8 years ago.
epydoc css file that generates a django styled api doc
update.sh (295 bytes) - added by django@… 8 years ago.
my update script to keep http://djangoapi.quamquam.org uptodate

Download all attachments as: .zip

Change History (10)

comment:1 Changed 8 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 8 years ago by django@…

epydoc css file that generates a django styled api doc

comment:2 Changed 8 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=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 8 years ago by django@…

  • Cc django@… added

Changed 8 years ago by django@…

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

comment:4 Changed 8 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 8 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 8 years ago by adrian

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

comment:7 Changed 7 years ago by SmileyChris

  • Triage Stage changed from Unreviewed to Design decision needed

comment:8 Changed 7 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.

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.