Fixed #24917 -- Made admindocs display model methods that take arguments.

3 files changed, 108 insertions, 9 deletions

diff --git a/django/contrib/admindocs/templates/admin_doc/model_detail.html b/django/contrib/admindocs/templates/admin_doc/model_detail.html
index 59d8abcd8f..6472119f54 100644
--- a/django/contrib/admindocs/templates/admin_doc/model_detail.html
+++ b/django/contrib/admindocs/templates/admin_doc/model_detail.html
@@ -27,6 +27,7 @@
 
 {{ description }}
 
+<h3>{% trans 'Fields' %}</h3>
 <div class="module">
 <table class="model">
 <thead>
@@ -48,6 +49,30 @@
 </table>
 </div>
 
+{% if methods %}
+<h3>{% trans 'Methods with arguments' %}</h3>
+<div class="module">
+<table class="model">
+<thead>
+<tr>
+    <th>{% trans 'Method' %}</th>
+    <th>{% trans 'Arguments' %}</th>
+    <th>{% trans 'Description' %}</th>
+</tr>
+</thead>
+<tbody>
+{% for method in methods|dictsort:"name" %}
+<tr>
+    <td>{{ method.name }}</td>
+    <td>{{ method.arguments }}</td>
+    <td>{{ method.verbose }}</td>
+</tr>
+{% endfor %}
+</tbody>
+</table>
+</div>
+{% endif %}
+
 <p class="small"><a href="{% url 'django-admindocs-models-index' %}">&lsaquo; {% trans 'Back to Model Documentation' %}</a></p>
 </div>
 {% endblock %}
diff --git a/django/contrib/admindocs/views.py b/django/contrib/admindocs/views.py
index 543b3e6b02..996650cefb 100644
--- a/django/contrib/admindocs/views.py
+++ b/django/contrib/admindocs/views.py
@@ -14,7 +14,10 @@ from django.db import models
 from django.http import Http404
 from django.template.engine import Engine
 from django.utils.decorators import method_decorator
-from django.utils.inspect import func_has_no_args
+from django.utils.inspect import (
+    func_accepts_kwargs, func_accepts_var_args, func_has_no_args,
+    get_func_full_args,
+)
 from django.utils.translation import ugettext as _
 from django.views.generic import TemplateView
 
@@ -219,7 +222,7 @@ class ModelDetailView(BaseAdminDocsView):
             fields.append({
                 'name': field.name,
                 'data_type': data_type,
-                'verbose': verbose,
+                'verbose': verbose or '',
                 'help_text': field.help_text,
             })
 
@@ -242,9 +245,10 @@ class ModelDetailView(BaseAdminDocsView):
                 'verbose': utils.parse_rst(_("number of %s") % verbose, 'model', _('model:') + opts.model_name),
             })
 
+        methods = []
         # Gather model methods.
         for func_name, func in model.__dict__.items():
-            if inspect.isfunction(func) and func_has_no_args(func):
+            if inspect.isfunction(func):
                 try:
                     for exclude in MODEL_METHODS_EXCLUDE:
                         if func_name.startswith(exclude):
@@ -254,11 +258,29 @@ class ModelDetailView(BaseAdminDocsView):
                 verbose = func.__doc__
                 if verbose:
                     verbose = utils.parse_rst(utils.trim_docstring(verbose), 'model', _('model:') + opts.model_name)
-                fields.append({
-                    'name': func_name,
-                    'data_type': get_return_data_type(func_name),
-                    'verbose': verbose,
-                })
+                # If a method has no arguments, show it as a 'field', otherwise
+                # as a 'method with arguments'.
+                if func_has_no_args(func) and not func_accepts_kwargs(func) and not func_accepts_var_args(func):
+                    fields.append({
+                        'name': func_name,
+                        'data_type': get_return_data_type(func_name),
+                        'verbose': verbose or '',
+                    })
+                else:
+                    arguments = get_func_full_args(func)
+                    print_arguments = arguments
+                    # Join arguments with ', ' and in case of default value,
+                    # join it with '='. Use repr() so that strings will be
+                    # correctly displayed.
+                    print_arguments = ', '.join([
+                        '='.join(list(arg_el[:1]) + [repr(el) for el in arg_el[1:]])
+                        for arg_el in arguments
+                    ])
+                    methods.append({
+                        'name': func_name,
+                        'arguments': print_arguments,
+                        'verbose': verbose or '',
+                    })
 
         # Gather related objects
         for rel in opts.related_objects:
@@ -282,6 +304,7 @@ class ModelDetailView(BaseAdminDocsView):
             'summary': title,
             'description': body,
             'fields': fields,
+            'methods': methods,
         })
         return super(ModelDetailView, self).get_context_data(**kwargs)
 
diff --git a/django/utils/inspect.py b/django/utils/inspect.py
index 3e3ad0ac23..597b2c095e 100644
--- a/django/utils/inspect.py
+++ b/django/utils/inspect.py
@@ -43,6 +43,44 @@ def get_func_args(func):
     ]
 
 
+def get_func_full_args(func):
+    """
+    Return a list of (argument name, default value) tuples. If the argument
+    does not have a default value, omit it in the tuple. Arguments such as
+    *args and **kwargs are also included.
+    """
+    if six.PY2:
+        argspec = inspect.getargspec(func)
+        args = argspec.args[1:]  # ignore 'self'
+        defaults = argspec.defaults or []
+        # Split args into two lists depending on whether they have default value
+        no_default = args[:len(args) - len(defaults)]
+        with_default = args[len(args) - len(defaults):]
+        # Join the two lists and combine it with default values
+        args = [(arg,) for arg in no_default] + zip(with_default, defaults)
+        # Add possible *args and **kwargs and prepend them with '*' or '**'
+        varargs = [('*' + argspec.varargs,)] if argspec.varargs else []
+        kwargs = [('**' + argspec.keywords,)] if argspec.keywords else []
+        return args + varargs + kwargs
+
+    sig = inspect.signature(func)
+    args = []
+    for arg_name, param in sig.parameters.items():
+        name = arg_name
+        # Ignore 'self'
+        if name == 'self':
+            continue
+        if param.kind == inspect.Parameter.VAR_POSITIONAL:
+            name = '*' + name
+        elif param.kind == inspect.Parameter.VAR_KEYWORD:
+            name = '**' + name
+        if param.default != inspect.Parameter.empty:
+            args.append((name, param.default))
+        else:
+            args.append((name,))
+    return args
+
+
 def func_accepts_kwargs(func):
     if six.PY2:
         # Not all callables are inspectable with getargspec, so we'll
@@ -64,10 +102,23 @@ def func_accepts_kwargs(func):
     )
 
 
+def func_accepts_var_args(func):
+    """
+    Return True if function 'func' accepts positional arguments *args.
+    """
+    if six.PY2:
+        return inspect.getargspec(func)[1] is not None
+
+    return any(
+        p for p in inspect.signature(func).parameters.values()
+        if p.kind == p.VAR_POSITIONAL
+    )
+
+
 def func_has_no_args(func):
     args = inspect.getargspec(func)[0] if six.PY2 else [
         p for p in inspect.signature(func).parameters.values()
-        if p.kind == p.POSITIONAL_OR_KEYWORD and p.default is p.empty
+        if p.kind == p.POSITIONAL_OR_KEYWORD
     ]
     return len(args) == 1