On 25.07.2013, at 14: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 assuming you want to move it into an own package and release it on PyPI. I have some experience with that now due to localflavor and would love to share that with anyone willing to spearhead the separation. Jannis PS: I just squatted 'django-admindocs' on PyPI. -- 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.
