Opened 19 years ago
Closed 18 years ago
#1248 closed enhancement (wontfix)
[patch] API Reference
| Reported by: | 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: | no | UI/UX: | no |
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)
Change History (10)
comment:1 by , 19 years ago
by , 19 years ago
| Attachment: | api_css.diff added |
|---|
epydoc css file that generates a django styled api doc
comment:2 by , 19 years ago
| 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 by , 19 years ago
| Cc: | added |
|---|
by , 19 years ago
my update script to keep http://djangoapi.quamquam.org uptodate
comment:4 by , 19 years ago
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 by , 19 years ago
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 by , 19 years ago
| priority: | normal → low |
|---|---|
| Severity: | normal → minor |
comment:7 by , 18 years ago
| Triage Stage: | Unreviewed → Design decision needed |
|---|
comment:8 by , 18 years ago
| Resolution: | → wontfix |
|---|---|
| Status: | new → 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.
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.