+1
On 25 July 2013 13:29, Aymeric Augustin <[email protected]>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 > > -- > 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 [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. > > > -- 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.
