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 -- Aymeric. -- 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.
