Question

我使用django admindocs作为文档，基本功能很好用（我可以访问doc页面，模型列出了文档，help_text包含在内等）。

不幸的是，文档字符串中的reStructuredText标记被完全忽略，例如

超链接未转换为超链接
子弹列表不是项目符号列表
Django标记，例如：model：appname.ModelName未解析

我正在使用Django的开发中继版本（1.7）

以下是我正在使用的文档字符串的示例：

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' )
    ...

当我将上述文档字符串内容粘贴到休息编辑器（我使用http://rst.ninjs.org/）时，一切都按预期工作。

转换适用于记录方法的文档字符串，例如

def my_method(self):
    """Docstring Heading

    1. Listitem 1
    2. Listitem 2

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

正确转换。

我确定，我错过了一些非常明显的事情，不是吗？

Answer 1

然后 admindocs 模块的行为与Django 1.4相同。

要从python文件自动生成可导航的文档，Python Sphinx http://sphinx.pocoo.org/可能是更好的方法，将生成文件放在另一个伪静态文件夹中。
为此，请将sphinx文档复制到模板文件夹，并添加自定义urls(..)和view，以提供对限制设置为仅限员工的文件的访问权限（例如，通过规范装饰者login_required和user_pases_test。

其他解决方案：

不幸的是，有关第一次使用的文档有些缺乏，例如settings.py参数RESTRUCTUREDTEXT_FILTER_SETTINGS。

向您保证，为了激活这些过滤器，django.contrib.markup'会添加到您的settings.py中的INSTALLED_APPS设置和模板中的{% load markup %}。

您应该安装docutils。如果未安装，您将不会收到错误。将linux与bash一起使用时，请输入：

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

直接渲染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)

您可以通过循环遍历所有[相关]模型及其__docs__属性来自动执行此操作，随后将字符串呈现为reStructuredText，如下所示：

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)

Django admindoc没有呈现reStructuredText

1 个答案: