Some love for admindocs

[Žan Anderle]

Hi folks!

I've been thinking about admindocs lately and that they would really deserve more attention than they currently get. It's a quite useful feature and I think a very underrated one.

They were initially there to provide documentation for 'front-end people', when working on templates. While this may still be useful, we've already discussed that nowadays it's more common to use admindocs as internal documentation for developers. I think I'd be great if this position was reaffirmed inside the Django project. Some of the ways we could do that:

1. Have that position more clearly stated in the documentation for admindocs

2. Mention admindocs in other parts of the Django documentation. For example, it seems that following FK relations is often a lot easier with admindocs. Maybe that should be mentioned somewhere?

3. Mention admindocs in the tutorial. Not sure about this one, since it could just add unnecessary weight. But it might also make life easier for some people.

4. Add some possible new features:

• documenting management commands 
• having some kind of README per app. Tim Baxter provided an example/possible implementation of this on the irc channel. 

Anyway, I'd love to hear your thoughts.

Best,

Žan

[Tim Graham]

It might be interesting to fork it and develop your vision as a separate project so you can iterate more quickly. At some point we could evaluate whether the existence of an actively maintained external package would allow us to deprecate the version in Django itself (as has been previously proposed but rejected because it doesn't have a big maintenance overhead and some people like it).

Here's that discussion: https://groups.google.com/d/topic/django-developers/0-qFyCPuSRs/discussion

[Tim Baxter]

For the reasons outlined in the comments there, and for the reasons outlined by Zan above, I think it should be kept and developed. I believe it's one of the most-underutilzed features in Django, and is invaluable for both beginners finding their way around and experienced developers who need a solid overview of the third-party lib they just grabbed.

Yes, there are shortcomings, but that's reason to improve them, not throw them out.