On Jan 11, 3:36 am, mrmclovin <simw...@gmail.com> wrote: > On Jan 11, 7:44 am, Sam Lai <samuel....@gmail.com> wrote: > > > > > > > > > > > On 11 January 2011 13:39, Christophe Pettus <x...@thebuild.com> wrote: > > This isn't about patches to the existing docs (which are great for > > their purpose). It is about Django missing an API reference manual, > > something like .NET Class Library Reference > > (http://msdn.microsoft.com/en-us/library/gg145045.aspx), PHP's > > Function Reference (http://www.php.net/manual/en/funcref.php) or > > Java's (rather hideous looking) API reference > > (http://download.oracle.com/javase/6/docs/api/). > > > I'm glad someone brought this up (although 'horrible' seems like too > > strong a word). I miss not having these docs in some online form > > because once you know enough about Django, you often know that Django > > has capability x but you don't remember what class/namespace it is in. > > You end up having to google and spend a while locating the info in the > > existing docs. Browsing or grepping the code isn't much better (maybe > > I'm missing an app or two here). > > > API docs also tend to be more structured and concise so you can > > instantly see what parameters take what, what exceptions might be > > thrown, what the return value is/represents etc. > > > Right now, I almost always have a browser tab open to > > code.djangoproject.com for this purpose. > > > Talk/ideas are cheap, so here's my take on possible API docs for Django - > > > An API reference site structured in a similar manner to the above > > examples, with the ability to easily search; integrated pydocs; links > > to relevant sections of the Django docs; a link to see the code of the > > function/class/method etc. A wiki-style section for each page would be > > nice too to document caveats, tips, tricks, relevant snippets etc. > > > Of course the dynamic nature of the code makes this harder to do and > > will probably require some human intervention to ensure an entry > > exists for every parameter, mapped method etc. > > > P.S. what's the short answer to why the current Django docs aren't on > > a wiki site instead of being versioned inside SVN? > > > There are some minor clarifications here and there that I'd like to > > add, but the overhead of producing a patch, creating a ticket, > > flagging down a committer, getting a consensus, and finally having the > > patch committed is a bit off-putting. I can understand the process for > > code, but it just seems a bit over-the-top for docs. Maybe a > > compromise would be adding something like the per-paragraph comments > > that The Django Book site has; that way the docs stay official, yet > > there's still a way for users to add to them. > > > > -- > > > -- Christophe Pettus > > > x...@thebuild.com > > > > -- > > I guess your post should be replaced by my first one :). It's exactly > what I was trying to say: django need a reference manual to complement > the existing documentation. > > On Jan 11, 8:55 am, James Bennett <ubernost...@gmail.com> wrote: > > > If your computer is incapable of running pydoc, epydoc or other > > similar scripts, how is it simultaneously able to run Django? > > -- > > "Bureaucrat Conrad, you are technically correct -- the best kind of > > correct." > > If you bought a game, would you rather like to get info on how to > compile the game in order to play it.. or just install it and play it?
That's a stupid analogy, django devs have limited time and there are things in django itself and existing docs that could be improved. I would prefer if they spent the time on more important things rather than relatively less important, e.g. things that can be done automatically by modules like pydoc. OTOH I would also appreciate it if someone made an nice online module reference for django. I don't need it very often, but when I do, it'd be nice to have, no doubt. I think it's unfair to say Django docs are bad -- to the contrary, they're the best docs I've seen in an open source project. And forum interfaces and especially searching is pathetically bad, I always end up using google to search forum sites instead of built-in search. -- You received this message because you are subscribed to the Google Groups "Django users" group. To post to this group, send email to django-us...@googlegroups.com. To unsubscribe from this group, send email to django-users+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-users?hl=en.
