documentation models skips some methods

[miked@…]

Admin docs are brilliant and the documentation at ​https://docs.djangoproject.com/en/dev/ref/contrib/admin/admindocs/#model-reference optimistically says "The models section of the admindocs page describes each model in the system along with all the fields and methods available on it."

In fact it skips methods unless they have exactly one argument.

This bothers me because I sometimes want model methods to have additional args. It would be better to permit any number of args.

In contrib/admindocs/views.py at the end of line 235 if one adjusts == 1 to > 0 it reveals the skipped methods with no apparent side effects.

There must be a reason it was set this way but maybe it is no longer an issue.

Here is the patch:

+++ contrib/admindocs/views.py  Fri Oct 12 16:31:45 2012
@@ -232,7 +232,7 @@

     # Gather model methods.
     for func_name, func in model.__dict__.items():
-        if (inspect.isfunction(func) and len(inspect.getargspec(func)[0]) == 1):
+        if (inspect.isfunction(func) and len(inspect.getargspec(func)[0]) > 0):
             try:
                 for exclude in MODEL_METHODS_EXCLUDE:
                     if func_name.startswith(exclude):

If this patch is accepted, it makes the app match the documentation so no change to the docs would be required.

[Łukasz Rekucki]

From my understanding the intended audience for docs generated by admin docs, are template authors. Thus documenting methods that have more then one argument (i.e. any explicit arguments you will need to pass) isn't helpful as you *can't* use them from a template. For generating developer documentation of your classes you might want to check out Sphinx.

Of course feel free to reopen if you disagree.

PS. Patches should be attached to the ticket as a full diff, not in the description. And every patch needs tests.

[miked@…]

Replying to lrekucki:

From my understanding the intended audience for docs generated by admin docs, are template authors. Thus documenting methods that have more then one argument (i.e. any explicit arguments you will need to pass) isn't helpful as you *can't* use them from a template.

Ok. I get it. I didn't understand the target audience.

For generating developer documentation of your classes you might want to check out Sphinx.

Of course feel free to reopen if you disagree.

I don't disagree so I won't reopen it.

However, I do think a additional arguments which provide defaults are effectively the same as not having additional arguments AND therefore should be interesting for template authors.

The reason I wrote this ticket in the first place is because I saw admindocs as a brilliant way to start documenting an API for my project. I will check out Sphinx but having it all there already was super attractive.

PS. Patches should be attached to the ticket as a full diff, not in the description. And every patch needs tests.

Thanks for the advice. I'll follow it next time.

Mike