Can we assume it will be separated out? While none of us on the list use admindocs or care, a decent number of beginners seem to like to use it.
--Daniel Greenfeld On Thursday, July 25, 2013 7:21:08 PM UTC+2, Julien Phalip wrote: > > On Jul 25, 2013, at 5:29 AM, Aymeric Augustin < > aymeric....@polytechnique.org <javascript:>> wrote: > > > Hello, > > > > I'd like to deprecate admindocs. Here are my reasons: > > > > 1) It's called the "documentation generator", but it only operates on > docstrings. This promotes the idea that docstrings are appropriate > documentation, while the Python and Django communities now favor prose > documentation. > > > > 2) Even though it's possible to use docstrings to generate API > documentation, for instance with Sphinx' autodoc, I find that heavily > formatted, Javadoc-style docstrings (or late epydoc-style) [1] tend to be > hard to read for humans and I don't want Django to encourage them. > > > > 3) Its age shows [2]; it was a decent idea at the time it was created > but the standard for documentation has evolved a lot since then. > > > > 4) The featureset is very reminiscent of Django's origins, see for > example the "edit this object" bookmarklet. > > > > 5) Generating documentation doesn't belong to a web framework. There are > better tools for this purpose — namely, Sphinx. > > > > 6) There are a few old, unresolved tickets with patches, indicating low > interest [3]. > > > > 7) Test coverage is low (22%), discouraging contributions. > > > > 8) We could get rid of the optional dependency on docutils. > > > > What do you think? > > > > [1] > https://docs.djangoproject.com/en/dev/ref/contrib/admin/admindocs/#view-reference > > > [2] > https://code.djangoproject.com/wiki/BackwardsIncompatibleChanges#Movedadmindocviewsintodjango.contrib.admindocs > > > [3] > https://code.djangoproject.com/query?status=!closed&component=contrib.admindocs > > > That sounds reasonable to me. +1 -- You received this message because you are subscribed to the Google Groups "Django developers" group. To unsubscribe from this group and stop receiving emails from it, send an email to django-developers+unsubscr...@googlegroups.com. To post to this group, send email to django-developers@googlegroups.com. Visit this group at http://groups.google.com/group/django-developers. For more options, visit https://groups.google.com/groups/opt_out.
