Django docstring 和 Sphinx 的未知解释文本角色“设置”答案

【问题标题】：Unknown interpreted text role "setting" with Django docstring and SphinxDjango docstring 和 Sphinx 的未知解释文本角色“设置”
【发布时间】：2019-06-28 08:56:51
【问题描述】：

我正在记录一个 Djagno 2.2 应用程序。

Django documentation 状态链接到设置为

Add :mod:`django.contrib.auth` to your :setting:`INSTALLED_APPS`...

在我的文档中，声明是

The length is defined in the :setting:`URL_ID_LENGTH`

使用 Sphinx

生成文档时

make html

给出警告

:docstring of app.models.Class.function:4: WARNING: Unknown interpreted text role "setting".

我已将 sphinx.ext.intersphinx 添加到 Sphinx 的 conf.py。

【问题讨论】：

标签： django python-sphinx

【解决方案1】：

根据Django documentation，它有自己的特定标记。

您需要将 Django 的 conf.py 中的 djangodocs 添加到您的：

extensions = [
    "djangodocs",
    'sphinx.ext.extlinks',
    "sphinx.ext.intersphinx",
    "sphinx.ext.viewcode",
]

然后将djangodocs extension file 放入您的docs/_ext/djangodocs.py。

最后import its path 是这样的：

sys.path.append(abspath(join(dirname(__file__), "_ext")))

【讨论】：

在 Django 文档中是否说明有一个名为“djangodocs”的 Sphinx 扩展？
不，它只是声明它有自己的特定标记，包括:setting:。我以为这是在他们的 conf.py 某处定义的自定义角色，但发现这是他们自己的扩展。
Django 有关于 Django 特定标记的文档。但是没有关于如何使用它。他们应该在文档本身中有它。
这个问题很快被解决为“无效”。问题仍然是没有文档说明您需要启用“djangodocs”扩展才能使用特定于 Django 的标记。
我猜他们认为开发人员在编写自己的附加组件/扩展/等时会“知道”它。对于姜戈。 :/ 我鼓励@AnujTBE 详细说明为什么这对编写文档的开发人员来说是个问题。