Django admin documentation generator not formatting Docstrings for Models

Question

I'm currently in the process of documenting all of my django views and models using the Django admin documentation generator. While I haven't had any problems at all documenting views, however anything written in the docstrings of my Models are rendered just as plaintext in the documentation.

In other words, if I want to reference a view:

:view:`appname.view_name`

will be rendered as a link (what I want) if inserted into the docstring of a view, but will show up as ":view:`appname.view_name`" in plaintext when inserted into the docstring of any model. However, when inserted in model's method, formatting works as expected again.

At first I thought this was a quirk of the documentation generator, that maybe it doesn't read the markup for model docstrings, but after reading the documentation (found here: https://docs.djangoproject.com/en/1.5/ref/contrib/admin/admindocs/#model-reference ) it seems that you I should be able to link to other parts of the documentation.

I haven't seen anyone else having this problem, and I'm not sure where to start looking for a solution. Thanks in advance for any expertise and explanations.

EDIT:

It seems like formatting is skipped entirely in Model's docstring - ie it will ignore reStructured text.

For example

class MyModel(models.Model):

"""

Title

"""

will show up simply as Title in plaintext in django admin docs.

Answer 1

Django admin document generator currently (1.7 at time of writing) does not support reStructure text in model docstrings.

This was addressed in card #5405 but still hasn't been merged in master as it created some merge conflicts. Last change:

I left comments on the ​pull request but it still needs some improvement including a rebase to merge cleanly. It would also be good to mention the change in the release notes.