7

通过正确的 intersphinx 设置，您可以从自己的文档中链接到 Django 类，如下所示：

:class:`django:django.db.models.Model`

但是你如何链接到一个设置？Django 使用它自己的:setting:构造而不是像:class:. 如何链接到带有 intersphinx 的设置？

我尝试了各种咒语，但都没有奏效（有些可能是完全错误的）：

:ref:`django:ROOT_URLCONF`
:ref:`django:root_urlconf`
:setting:`django:ROOT_URLCONF`
:ref:`django:setting:ROOT_URLCONF`
:django:setting:`ROOT_URLCONF`

错误喜欢undefined label: django:root_urlconf并Unknown interpreted text role "setting"打招呼。

4

2 回答 2

10

问题：我本地的 sphinx 不知道 Django 的自定义 sphinx 角色，例如setting. 所以像这样一个非常好的 intersphinx 参考：

:django:setting:`ROOT_URLCONF`

在您告诉 Sphinx 有关 intersphinx 目标的自定义角色之前，它不会起作用。

最后，通过从Django 的 sphinx 扩展中复制一个小片段作为_ext/djangodocs.py我的文档旁边的一个小片段使其工作：

def setup(app):
    app.add_crossref_type(
        directivename = "setting",
        rolename = "setting",
        indextemplate = "pair: %s; setting",
    )

我将以下内容添加到我的 Sphinx' 中conf.py：

import os
import sys

...

sys.path.append(
    os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext")))
# ^^^ I'll do that neater later on.

extensions = ['djangodocs',
              # ^^^ I added that one.
              'sphinx.ext.autodoc',
              ...
              ]

...

所以：intersphinx 有效，但是如果您指向自定义角色，则需要在本地定义该自定义角色。

于 2012-12-01T20:16:00.900 回答
2

您需要查看 django 的 objects.inv 以确定正确的交叉引用应该是什么。

看起来：

:std:setting:`ROOT_URLCONF <django:ROOT_URLCONF>`

应该管用。

不知何故，我有 django 的 objects.inv，但找不到我从中检索到的 URL，理论上它应该是https://docs.djangoproject.com/en/1.4/objects.inv但最终会重定向几次在未找到文件的错误中。

于 2012-11-15T22:34:14.157 回答