如何在项目中引用具有部分ID的另一页？

问题描述

This只要我不需要特定的部分就可以正常工作-似乎可以使用：name <page.html>_，除非我重复name Sphinx抛出

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>` （不是）

解决方法

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

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

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

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

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

最后但并非最不重要：

1. 假设您有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对象），会发生什么？？？它被插入到狮身人面像索引中！！！为什么这么重要？因为您可以将其作为Python模块进行交叉引用（毕竟，包是模块），而不必将其作为文档或部分进行交叉引用。这使您的文档，索引和交叉引用具有整体一致性。

最终结果？您从不会看到HTML或锚点。 Sphinx为您管理/生成/编制所有索引。这就是您真正想要的。完整的抽象层。

有人会提出异议：

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

容易解决的问题是，在.rst文件中的Docstring和ReST / Sphinx语法中使用纯英文（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>`

不需要锚点。更加干净和光滑。