Question

我有一个广泛使用django管理界面的应用程序。

管理GUI中的某些内容需要说明（特定于域/模型的文档）。

我们使用狮身人面像，而屏幕截图会解释详细信息。

是否存在一种通用/自动的方法来创建从模型实例的django管理界面到文档中匹配部分的超链接？

我知道我可以更改模型的管理模板，但是以某种方式，我认为有人对如何以更专业的方式解决这个问题有更好的主意。

就我而言，文档托管在同一服务器上。 AFAIK如果您有一个很大的梦想，这也是需要的，那么文档中也有到django应用程序的链接（但这是一个不同的问题）。

“匹配文档中的部分”是什么意思？

想象一下，我有一个名为“ Foo”的模型。

我有该模型的文档（包括图片）。

现在，我想要从模型的管理页面到模型“ Foo”的文档的超链接。

我认为这是一个非常普遍的问题。我认为很遗憾，框架和第三方应用程序都无法帮助编写集成文档。

Answer 1

这是我用来在管理网站中为特定模型创建链接的方法。

class YourModelAdmin(admin.ModelAdmin):

    def link_to_doc(self,obj):
        link = 'https://www.stackoverflow.com'
        return u'<a href="%s">%s</a>' % (link, "Link Name")

    link_to_doc.allow_tags = True
    link_to_doc.short_description = "Link Description for admin"

    fields = (
         'your_model_fields',
         'link_to_doc'           
    )

    readonly_fields = (
         'your_model_readonly_fields',
         'link_to_doc'           
    )


admin.site.register(YourModel, YourModelAdmin)

Answer 2

这个问题是特定的，据我所知，Django很可能没有现成的解决方案。

但是，由于要求在模型管理员中提供链接（URL），因此可以使用模型类中的虚拟属性轻松实现。

我们有一个模型Foo：

class Foo(models.Model):
    bar = models.CharField(max_length=255)
    baz = models.IntegerField()

和模型管理员FooAdmin：

class FooAdmin(admin.ModelAdmin):
    list_display = ('bar', 'baz')
    fields = ('bar', 'baz')

现在，我们想提供一个指向管理员文档的链接。假设文档是根据.rst文件自动生成的，并且遵循通用的网址格式，则可以在这样的链接下找到这些文档：

http://localhost:8000/docs/foo/

最终，URL在urls.py中定义如下（伪代码）：

url(r'docs/(?P<model>\w+)/$', ViewClass.as_view(), name='docs')

牢记这些假设，我们将以下内容添加到模型类中：

from django.db import models
from django.utils.html import format_html
from django.urls import reverse

class Foo(models.Model):
    bar = models.CharField(max_length=255)
    baz = models.IntegerField()

    @property
    def docurl(self):
        url = reverse('docs')
        return format_url(
            '<a href="{url}">{model}</a>',
            url=url,
            model=self._meta.model_name
        )

在模型管理员中，我们可以将属性docurl用作只读字段：

class FooAdmin(admin.ModelAdmin):
    list_display = ('bar', 'baz')
    fields = ('bar', 'baz', 'docurl')
    readonly_fields = ('docurl',)

由于属性docurl将在所有模型中使用，因此最好为项目创建一个基础模型类，在其中创建属性，并让所有其他模型类都从该类继承。

您的实际情况可能与此示例不同，但是基本思想是在模型属性中检索/生成文档url，然后将该属性用作模型admin中的只读字段。

与提出直接在模型admin中生成url的其他解决方案相比，优点是将业务逻辑放入模型中。这样docurl可以在许多不同的地方使用。

Answer 3

不知道该告诉您什么，但是您如何与included batteries一起使用：

Django的admindocs应用从INSTALLED_APPS中的任何应用的模型，视图，模板标签和模板过滤器的文档字符串中提取文档，并从Django管理员处获取该文档。

由于文件使用sphinx-autodoc（而不是链接）存储在.rst文件而不是docstrings中，因此您仍然可以使用此机制，方法是提供一些帮助字符串作为类文档，然后链接到更详尽的文档：

class Joy(models.Model):
    """
    The purpose of this model is to provide you with daily joy.
    How to achieve this is  outlined in the
    `documentation <https://docs.example.com/models/Joy>`_.
    """

Django：从模型管理员到文档的超链接

3 个答案: