问题
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.
回答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.
来源：https://stackoverflow.com/questions/22230904/django-admin-documentation-generator-not-formatting-docstrings-for-models