Ticket #22428: 22428-1.diff

django/contrib/admindocs/views.py

@@ -262 +262 @@
                 'data_type': 'Integer',
                 'verbose': utils.parse_rst(_("number of %s") % verbose, 'model', _('model:') + opts.model_name),
             })
+
+        verbose = utils.parse_rst(utils.trim_docstring(model.__doc__), 'model', _('model:') + opts.model_name)
         kwargs.update({
             'name': '%s.%s' % (opts.app_label, opts.object_name),
             # Translators: %s is an object type name
             'summary': _("Attributes on %s objects") % opts.object_name,
-            'description': model.__doc__,
+            'description': verbose,
             'fields': fields,
         })
         return super(ModelDetailView, self).get_context_data(**kwargs)

tests/admin_docs/models.py

@@ -18 +18 @@
 
 
 class Person(models.Model):
+    """
+    Similar as :model:`auth.User`.
+    """
     first_name = models.CharField(max_length=200, help_text="The person's first name")
     last_name = models.CharField(max_length=200, help_text="The person's last name")
     company = models.ForeignKey(Company, help_text="place of work")

tests/admin_docs/tests.py

@@ -236 +236 @@
 
     def test_descriptions_render_correctly(self):
         """
-        The ``description`` field should render correctly for each type of field
+        The ``description`` field should render correctly for the model itself
+        and for each type of field.
         """
+        link = '<a class="reference external" href="/admindocs/models/%s/">%s</a>'
+        markup = '<p>the related %s object</p>'
+
+        # model docstring
+        auth_markup = link % ("auth.user", "auth.User")
+        self.assertContains(self.response, auth_markup)
+
         # help text in fields
         self.assertContains(self.response, "<td>first name - The person's first name</td>")
         self.assertContains(self.response, "<td>last name - The person's last name</td>")
@@ -245 +253 @@
         # method docstrings
         self.assertContains(self.response, "<p>Get the full name of the person</p>")
 
-        link = '<a class="reference external" href="/admindocs/models/%s/">%s</a>'
-        markup = '<p>the related %s object</p>'
         company_markup = markup % (link % ("admin_docs.company", "admin_docs.Company"))
 
         # foreign keys