Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#19116 closed Uncategorized (invalid)

documentation models skips some methods

Reported by: miked@… Owned by: nobody
Component: contrib.admindocs Version: 1.4
Severity: Normal Keywords: skip methods
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: yes UI/UX: no

Description

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.

Change History (2)

comment:1 follow-up: Changed 3 years ago by lrekucki

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement set
  • Resolution set to invalid
  • Status changed from new to closed

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.

comment:2 in reply to: ↑ 1 Changed 3 years ago by 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

Note: See TracTickets for help on using tickets.
Back to Top