On Jul 25, 2013, at 5:29 AM, Aymeric Augustin <aymeric.augus...@polytechnique.org> 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.
