Deprecate admindocs?

[Aymeric Augustin]

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.

[Marc Tamlyn]

+1

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

[Elyézer Rezende]

I'd recommend putting it in a separate repo, just in case any user miss it.

Considering the above, +1

--
Elyézer Rezende
http://elyezer.com

[Daniele Procida]

On Thu, Jul 25, 2013, Aymeric Augustin <aymeric....@polytechnique.org> wrote:

>I'd like to deprecate admindocs.

I love admindocs.

When I first started using Django, I would always find ready to hand, and the fact that it was right there, in the interface of the thing I was working with, really helped me build a picture in my head of the way the system worked together and what was available.

Particularly useful was the automatic linking to related objects.

I refer to admindocs regularly still. There might be other ways to check for example what fields or attributes a model has, but I can't think of a quicker one, or one that automatically keeps itself up-to-date with the state of the model with no action required.

I'd hate to see it go.

Daniele

[Loic Bistuer]

+1

--
Loic

[AJ B]

If it was put in a separate repo. +1

[Julien Phalip]

That sounds reasonable to me. +1

[Jannis Leidel]

On 25.07.2013, at 14:29, Aymeric Augustin <aymeric....@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 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.

[Daniel Greenfeld]

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

[Michael Radziej]

Aymeric Augustin <aymeric....@polytechnique.org> writes:

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

Weeeeelllll ... it's a matter of target group.

Of course the docstring generated admindocs are no substitute for well
written documentation. But they are vital for you if your workflow
includes handing your rough will-do templates to your customer or a
separate department that handles all the graphic design.

At that point, it's really important for the template writers to have an
on-hand description of views and models. Things are usually still in a
flux, and documentation in the source code is more easily kept up to date.

A big motivation for removing a package from core Django has always been
that it removes the dependency of the release cycles and allows faster
development of the out-sourced part. Is this really a valid point here?
I don't see a lot of needs here. There are currently 4 open tickets for
admindocs, none of it makes me any worries.

I won't say that the admindocs are necessarily a part of core Django,
but, I see it as an advantage here since it helps keeping it in sync.

For your remaining items, I don't see the real issues behind them. It
does not keep anybody from writing proper documentation if they want, an
optional dependency does not hurt, and only few tickets and low test
coverage is just a sign of an old system that's been around for a long
time and does what is needed.

So, all in all, I'm -1 on this as long as there's no better reason.


Kind regards

Michael

[Aymeric Augustin]

2013/7/25 Aymeric Augustin <aymeric....@polytechnique.org>

I'd like to deprecate admindocs.

Given the feedback, I'll put this plan on hold for the time being. Thank you.

--
Aymeric.

[Collin Anderson]

Looking at the code, we're only using docutils for parsing reST markup in docstrings. What if we made reST parsing (and docutils) optional? Seems to me admindocs would still be plenty helpful without it.