如何使用部分 ID 引用项目中的另一个页面？

Question

This 工作正常，只要我不需要特定部分 - 这似乎工作：name <page.html>_，除非我重复 name Sphinx throws

WARNING: Duplicate explicit target name: "name"

即使它是无害的，它也会在我的应用程序中快速填充屏幕。

我知道原始的基于 HTML 的解决方法，但这是一种不鼓励的做法；有没有更“原生”的方法？

---

示例：

• `docs <package.html#module-package.callbacks>`_（有效）

• :doc:`docs <package.html#module-package.callbacks>` （没有）

• :doc:`docs <package#module-package.callbacks>` （没有）

Answer 1

如果您的目标是在内部交叉引用您的项目，我认为这不是使用 intersphinx 的好方法。

此时必须注意：当使用 automodule 或 autoclass 之类的 autodoc 指令之一时，该 Python 对象被放置在 Sphinx 索引中并且可以交叉引用。

但这提出了一个问题：如何交叉引用 ReST 部分？它被认为是arbitrary location，因为它们不是对象，并且它们不会通过 autodoc 指令（或通过 .rst 中的 py 域声明）插入到 Sphinx 索引中。

嗯，在这种情况下，有 4 个主要选项需要考虑（最后一个可能是最不明显的，因此也是最重要的）：

1. 使用 ReST hyperlink targets directly above the section。
2. 将 Python 域引用直接用于该部分下方的 autodoc 指令。
3. 如果该部分位于.rst文件的顶部，请使用cross-reference to the document。

最后但并非最不重要的一点：

4. 假设您有 1 个.rst 文件，其中记录了一个或多个包（比如说your_package.utils）。正常的 ReST 规则让您在文件顶部放置 1 个部分。但是没有自动模块指令，因为包可能是一个没有文档字符串的空__init__.py...那么在这种情况下最好的解决方案是什么？

*****************
your_package.UTIL
*****************

.. py:module:: your_package.UTIL


Modules
=======

(...the usual stuff...)

好的！！！现在，通过在 ReST 部分上方或下方明确声明 your_package.util 为 Python module（或任何可能适用的 Python 对象）会发生什么？它被插入到 Sphinx 索引中！！！为什么这很重要？？因为您可以将其作为 Python 模块（包毕竟是模块）进行交叉引用，而不必将其作为文档或部分进行交叉引用。这使您的文档、索引和交叉引用具有整体一致性...

最终结果？您永远不会看到 HTML 或锚点..!! Sphinx 为您管理/生成/索引所有这些。这就是你真正想要的。一个完整的抽象层。

有些人会提出异议：

• “您将 Sphinx/ReST 放入 Python 文档字符串中（人们不知道如何阅读）。”

很容易解决，将简单的英语放在 Docstring 中，并将 ReST/Sphinx 语法放在 .rst 文件中（autodoc 将加入这些部分）。

• 其他人会反对：“我想要在我的 ReST 中使用 HTML！”

当然可以，但是每当您编辑或重构某些内容时，它注定会成为一种痛苦。谁说看你的东西的普通 Python/ReST 开发人员什么都知道——或者想看——HTML 或锚点？

因此，最合理的分离遵循这些路线。

关于使用重复的目标名称：

没有真正的理由使用重复的目标名称。从您的 IDE 完成的重构最好使用唯一的目标名称。如果您决定移动 ReST 部分，那么上面的目标就会随之而来。

.. _this_section_without_duplicate_name:

*****************
Your ReST section
*****************

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`

不需要锚。更干净、更光滑。