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? You seem to be missing the point of having a convenient way of providing a reference manual. I didn't know about pydoc until now, maybe it's got what im looking for. However, I rather spend my time writing django code instead of using different 'tools' to get simple reference docs. -- 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.
