Extending contrib.admindocs functionality

[Žan Anderle]

contrib.admindocs will only document template tags and functions that can be invoked from templates. Therefore it has limited use. It would be really useful to be able to document all of the functions in the models (not just the ones that don't take any arguments). contrib.admindocs is a neat way of creating some basic documentation without any extra effort other than docstrings. By adding this feature, this potential could be fulfilled. Basically, you would get at least some documentation, just by writing docstrings (which you should be doing in the first place).

Because there might be need to keep the current functionality, I suggest the following solution. By default the docs would stay the same as they are now (show only the functions that can be invoked from templates), but we would add a "Show more" button, which would show all the functions instead.

This makes it easy, because there is no need for an extra setting in settings.py and it allows both new extended functionality and old functionality.

PS This is my first time suggesting a new feature, so please let me know, if I missed something!

[Marc Tamlyn]

This seems like a good idea to me. I'm not convinced that the original use case for admin docs (documenting features which only work in templates for the template author) is valid any more - especially with a Django in which you can use jinja2 easily where function calls are allowed. The separation between backend and template developers I tend to find is also much less clear than it once was, partly because it's trivial to write template code using documented features or properties which will quickly destroy performance. The use case of "quick and dirty docs for the team" seems more likely.

So overall, I'm in favour of adding this, possibly just by default not hidden. The hidden adds a level of backwards incompatibility which is nice.

Have you opened a ticket for this change? You may also wish to review the contributing guide.

Marc

--
You received this message because you are subscribed to the Google Groups "Django developers (Contributions to Django itself)" 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.
To view this discussion on the web visit https://groups.google.com/d/msgid/django-developers/fdba020d-486e-4e6f-8660-dcea7b7f5d38%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Žan Anderle]

Good point.

Yeah, I opened a ticket, but forgot to add it here. https://code.djangoproject.com/ticket/24917

Dne petek, 05. junij 2015 00.51.15 UTC+2 je oseba Marc Tamlyn napisala: