python - Django admindoc 不呈现 reStructuredText

Question

我将 django admindocs 用于文档，基本功能运行良好(我可以访问文档页面，列出模型和文档，包含帮助文本等)。

不幸的是，文档字符串中的 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' )
    ...

当我将上面的文档字符串内容粘贴到 rest 编辑器中时(我使用了 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 https://www.sphinx-doc.org可能是更好的方法，将生成的文件放在另一个伪静态文件夹中。
  为此，将 sphinx 文档复制到模板文件夹并添加自定义 urls(..) 和 view 以提供对文件的访问权限设置为 staff仅(例如通过规范装饰器login_required 和user_pases_test。

其他解决方案:

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

请放心，为了激活这些过滤器，django.contrib.markup' 已添加到您的 settings.py 和 {% 中的 INSTALLED_APPS 设置在模板中加载标记 %}。

您应该安装了 docutils。如果未安装，您将不会收到错误消息。当使用带有 bash 的 linux 时，输入:

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

---

直接渲染reStructuredText:

从 django 导入模板

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)