我将 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
已正确转换。
我敢肯定,我错过了一些非常明显的东西,不是吗?
最佳答案
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)
关于python - Django admindoc 不呈现 reStructuredText,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/18671860/