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

Posted 2021-04-10

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

管理GUI中的一些内容需要解释（域/模型特定的文档）。

我们使用sphinx和截图来解释细节。

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

我知道我可以改变模型的管理模板，但不知何故，我猜有人更好地了解如何以更专业的方式解决这个问题。

在我的情况下，文档托管在同一台服务器上。 AFAIK如果你有一个重要的梦想，那就是需要这个，那里也有从docs到django应用程序的链接（但这是一个不同的问题）。

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

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

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

现在我希望从模型的管理页面到模型“Foo”的文档有一个超链接。

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

答案

不知道该告诉你什么，但你如何使用included batteries：

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

由于您的文件位于.rst而不是使用sphinx-autodoc（链接以供考虑）的文档字符串，您仍然可以使用此机制，通过提供一些帮助字符串作为类文档，然后链接到更详细的文档：

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>`_.
    """

另一答案

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

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)

另一答案

这个问题是具体的，据我所知，很可能没有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文件自动生成的，并且遵循通用的URL模式，那么文档可以在以下链接下使用：

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

最终在urls.py中定义了这样的URL（伪代码）：

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将在所有模型中使用，所以最好为项目创建基础模型类，在那里创建属性，并让所有其他模型类从该类继承。

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

与其他解决方案相比，建议直接在模型管理中生成URL的优势在于将业务逻辑放入模型中。通过这种方式，docurl可以在许多不同的地方使用。