On Sun, 2010-07-04 at 18:41 -0700, dffdgsdfgsdfhjhtre wrote: > On Jul 4, 8:40 pm, Luke Plant <l.plant...@cantab.net> wrote: > > Unlike PHP, we have namespaces, which means that providing a list of > > every function/class is a different matter. > > So? Matplotlib has similar documentation to PHP's reference, and it's > fairly well regarded. The one thing that matplotlib doesn't do well is > the topical stuff which django does do well.
Namespaces mean that the same name can refer to different things - like 'Field', all the different 'utils' modules etc. So you can't have a shortcut that finds a single thing unless you also know which module it belongs to, but that seemed to be the major problem you were highlighting. > > Also, in the index, the location of each class/function is defined, so > > that if you are looking for something specific, you can indeed find > > where it lives pretty easily. (Again, it is not correct for > > RegexValidator at the moment because of the lack of module directive). > > I did not know this... Maybe we should have documentation for the > documentation.... Well, the front page says this in a box right at the top: Looking for specific information? Try the Index, Module Index or the detailed table of contents. and it's the Index you need in this case. > Also, another great thing about PHP's documentation is that each and > every function page is structured the exact same way. You may call it > 'boilerplate', but I call it 'consistent structure'. With PHP's > documentation, If you know exactly what you're looking for, you can > find it very quickly. For instance if you want to look up the order > of parameters the preg_replace function takes, you type "preg_replace" > into the search box, then move your eyes down to the first pink box. > That takes 2 seconds max. For django, if you wanted to know the order > of parameters the reverse() function takes, it will take you much > longer. That speed is because PHP has no namespaces (and makes little use of classes). In this case, when you say "reverse" do you mean django.core.urlresolvers.reverse or django.db.models.QuerySet.reverse? So in Django there *has* to be at least one extra step. Equivalent in Django docs: 1) type 'reverse' in the search box. Click on first hit, look at 'Contents' pane down the right, click 'reverse'. 2) Go to the General Index, click 'R', scroll to 'reverse' and choose the one you want. (or, go to General Index and use your browser search functionality e.g. type /reverse in Firefox.) I guess what you are really asking for is a search box that returns only exact matches from the index. > I'm not saying we should make the documentation longer. I'm proposing > we reorganize what we already have into two supersections; reference, > and topical, since they are aimed at separate audiences and serve > different purposes. We *already* have this - the Module Index and Index (clearly linked from the front page) are the reference sections, and most of the rest is topical, with links to the reference sections thrown in. > > Finally, some things do not have documentation regarding their import > > paths because they are not considered public. Even slugify is only > > 'public' as a template filter, and for that purpose it is a builtin and > > does not need to be imported. We currently make no guarantee that "from > > django.template.defaultfilters import slugify" will work in future > > AFAIK, or that it will be suitable for use outside the template system. > > (It already has some things, related to auto-escaping, that might make > > it behave 'funny' depending on what exactly you pass it). > > Then that should all should be documented! The fact that only documented functions are considered public *is* documented: http://docs.djangoproject.com/en/dev/misc/api-stability/ (This is part of the meta-documentation section) But the details of how the slugify function works should *not* be documented. It is a *private* implementation detail (at the moment at least). People who want to use it do so at their own risk, and should read the source. If you want to propose that these functions be considered public *as functions*, that is another matter. There are always various things that ought to become public if they are sufficiently useful outside of Django internals. I don't happen to think django.template.defaultfilters is in that category as it stands - the way those functions work is full of things that are very specific to the template system. > There has to be lots of people out there who use slugify and other > template functions outside templates. I don't thionk theres anything > wrong with encouraging people to do this as long as you make it clear > that these functions can move and that there may be side effects > from auto-escaping and such. But the point of the internal implementation details is that they can *change* - if we say "You can use these provided you are aware of points 1), 2) + 3)", we now have to *keep* points 1), 2) and 3), and we can't add points 4), 5) and 6). Without clairvoyance it is impossible to add the caveats that we need to add. And we already have the meta-documentation that says that only publicly documented code is considered stable (and programmers should in general be able to infer this anyway). Regards, Luke -- "We may not return the affection of those who like us, but we always respect their good judgement." -- Libbie Fudim Luke Plant || http://lukeplant.me.uk/ -- You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to django-develop...@googlegroups.com. To unsubscribe from this group, send email to django-developers+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/django-developers?hl=en.
