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 < > [email protected] <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 [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/django-developers. For more options, visit https://groups.google.com/groups/opt_out.
