On Mon, Jan 10, 2011 at 3:25 PM, Simon W <simw...@gmail.com> wrote: > For such a good web framework it's a shame that the documention is not > structured well .. at all. It consists of massive text put on a page with > some random examples. But examples is all there is. In other languages and > frameworks I'm used to have at least a well structed API documention listing > all methods and members of classes with some comment attached to them. They > also show the class heirachy, quick and simple. I spend more time searching > for minor stuff in the documention than writing code. The django project > should look into doxygen or some similar doc generator.
The way I see it, there are two types of documentation: 1. Documentation which must be written by human beings. 2. Documentation which can be generated automatically by software. The documentation you'll find on docs.djangoproject.com is the first type. It consists, in large part, of things people want to know about Django but which can't be worked out automatically by a piece of software scanning over the code and docstrings. Much of this is in the form of how-to documents, broad overviews, tutorials, etc. which walk you through some feature and provide example code for common use cases; this sort of documentation can only be produced by human beings who know Django fairly well and put in the time and effort to write. The second type of documentation seems to be what you're looking for. Things like big lists of classes and members with docstrings are useful, certainly, but they're not something which requires human effort to produce; as others in the thread have pointed out, there are quite a few good tools for Python which will scan over a codebase and spit out this information into the output format of your choice. And since this type of documentation can be generated by software any time you need it, there's not a whole lot of utility to putting it up on the site. So my recommendation for you would be to look at tools like epydoc, since they do exactly what you appear to be asking for; meanwhile we'll keep putting the efforts of the Django dev team into producing the documentation epydoc can't :) -- "Bureaucrat Conrad, you are technically correct -- the best kind of correct." -- 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.
