Django admindoc not rendering reStructuredText

Question

Im using django admindocs for documentation and the basic functionality works nicely (I can access the doc pages, models are listed an documented, help_text is included, etc.).

Unfortunately, reStructuredText markup in docstrings is completely ignored, e.g.

• Hyperlinks are not converted to hyperlinks
• Bullet Lists are no bullet lists
• Django markups such as :model:appname.ModelName are not resolved

I'm using the Development Trunk Version of Django (1.7)

Here is an example of a docstring I'm using:

class Adresse(models.Model):

    u"""Postanschrift

    Wird für 
     - Organisationen 
     - Personen 

    genutzt.

    Siehe auch https://docs.djangoproject.com/en/dev/ref/contrib/contenttypes/#generic-relations 

    """

    object_id    = models.PositiveIntegerField()
    content_type = models.ForeignKey(ContentType)
    of           = generic.GenericForeignKey('content_type', 'object_id' )
    ...

When I paste the above docstring content into a rest editor (I used http://rst.ninjs.org/), everything works as expected.

The conversion works for docstrings documenting methods, e.g.

def my_method(self):
    """Docstring Heading

    1. Listitem 1
    2. Listitem 2

    refers to :model:`personen.Person`
    """
    pass

ist correctly converted.

I'm sure, I missed something very obvious, didn't I?

Answer 1

Then the admindocs module's behavior is the same as in Django 1.4.

• To auto-generate navigatable docs from your python files, Python Sphinx https://www.sphinx-doc.org may be a better way, by putting the generates files in another pseudostatic folder.
  To do that copy the sphinx docs to a template folder and add a custom urls(..) and view that provides access to the files with restrictions set to staff only (for instance via the canonical decorators login_required and user_pases_test.

Other solutions:

Unfortunately the documentation regarding the rst-usage is somewhat lacking, such as the settings.py parameter RESTRUCTUREDTEXT_FILTER_SETTINGS.

Reassure yourself that in order to activate these filters, django.contrib.markup' is added to your INSTALLED_APPS setting in your settings.py and {% load markup %} in the template.

You should have docutils installed. You will not receive errors if it is not installed. When using linux with bash, enter:

if [[ -z `pip freeze | grep docutils` ]];  then sudo easy_install docutils;fi;

---

Directly rendering the reStructuredText:

from django import template

class Adresse(models.Model):
    doc = u"""Postanschrift

    Wird für 
     - Organisationen 
     - Personen 
    """
t = template.Template('{% load markup %}{{ contentstr|restructuredtext }}')
c = template.Context({'contentstr': doc})
__doc__ = t.render(c)

You could do this automated by looping through all [relevant] models and their __docs__ attribute to subsequently render the string as reStructuredText as follows:

from django.conf import settings
from django.db.models import get_app, get_models
from django import template

for appname in settings.INSTALLED_APPS:
  app = get_app(appname )
  for model in get_models(app):
    if hasattr(model, '__doc__') and model.__doc__ != "":
      t = template.Template('{% load markup %}{{ contentstr|restructuredtext }}')
      c = template.Context({'contentstr': model.__doc__})
      model.__doc__ = t.render(c)