Python sphinx 如何引用项目中具有节ID的另一页？

只要我不需要一个特定的部分，它就可以正常工作，这似乎是可行的：

name

，除非我重复

name

Sphinx抛出

警告：重复显式目标名称：“name”

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

我知道基于原始HTML的变通方法，但这是一种令人沮丧的做法；是否有更“本土”的方法

---

示例：

• `docs`

  （作品）

• ：doc:`docs`

  （不）

• ：doc:`docs`

  （不）

---

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

此时必须注意：当使用autodoc指令之一，如

automodule

或

autoclass

时，Python对象被放置在Sphinx索引中，并且可以交叉引用

但这提出了一个问题：如何交叉引用其余部分？因为它们不是对象，并且它们不是通过autodoc指令（或通过

.rst

中的py域声明）插入到Sphinx索引中，所以它被认为是一个

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

休息一下

使用Python域引用直接引用本节下面的autodoc指令

如果节位于

.rst

文件的顶部，请使用

最后但并非最不重要的是：

假设您有一个

.rst

文件记录一个或多个包（比如

您的_package.utils

）。正常的ReST规则要求您在文件顶部放置1个部分。但是没有automodule指令，因为包可能是空的

\uuuu init\uuuu.py

，没有docstring…那么在这种情况下，最好的解决方案是什么呢

好的！！！现在，通过在ReST部分的上方或下方显式声明

您的_package.util

为（或任何可能应用的Python对象），会发生什么？？？它被插入斯芬克斯索引中！！！为什么这么重要？？因为您可以将其作为Python模块（包毕竟是模块）进行交叉引用，而不必将其作为文档或部分进行交叉引用。这使您的文档、索引和交叉引用具有整体一致性

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

有些人会提出反对意见：

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

很容易解决，将简单的英语放在Docstring中，并将ReST/Sphinx语法放在

.rst

文件中（autodoc将连接部件）

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

的确如此，但无论何时你编辑或重构某些东西，它都注定会成为一种痛苦。谁说普通的Python/ReST开发人员看你的东西都知道——或者想看——HTML或锚

所以最合理的分离是沿着这些线进行的

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

没有真正的理由使用重复的目标名称。从IDE进行重构时，最好使用唯一的目标名称。如果您决定移动其余部分，则上面的目标将随之移动

.. _this_section_without_duplicate_name:

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

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`

_此\u节\u没有\u重复\u名称：
*****************
休息区
*****************
：ref:`NICE\u USER\u DISPLAY\u NAME`

---

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

删除了该问题，并引用了一个根本不适用的理由；这里没有“打字错误”，评论回复也没有解决问题。这是您自己的软件包文档，对吗？如果是这样，请使用。我想问这是什么意思：“它在我的应用程序中快速填充屏幕”？我不知道如何理解这个句子？@StevePiercy；我想您指的是

py:module:：

；有一个语法示例，我可以通过“文档”超链接到

deeptrain.html#module deeptrain.callbacks

？（即）@bad_编码员谢谢你的来信。我寻找了一种不插入显式引用的方法，但假设Sphinx不是这样工作的。

：doc:

或

：py:doc:

也会呈现，而不是不需要的超链接。我愿意插入引用，但您对渲染有何建议？我如何引用具有可点击超链接的模块？@OverLordGoldDragon我将不得不研究它，可能今晚晚些时候或明天早上。在做了一些实验之后，我宁愿推迟任何关于链接如何可视化呈现的评论。使用自定义样式覆盖代码样式。请参阅使用RTD主题的@OverLordGoldDragon<代码>：doc:和

：ref:

应呈现为不带方框样式的正常URL（但

：mod:

或

：obj:

具有方框）。使用

：any:

将识别Python对象的类型，使用适当的角色，并应用box样式。（请注意，模块是Python类型，而不仅仅是HTML页面。）如果您想摆脱该框，请选择3个选项：1-本地覆盖自定义样式。2.使用target plus

：ref:

3。将该模块/包放在自己的.rst中，并使用

：doc:

而不是

：mod:

。（注：没有

py:doc:

有一个

py:mod:

，还有一个

：doc:

不是py。）@overordgolddragon很抱歉回答晚了。今天是星期六。。。

.. _this_section_without_duplicate_name:

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

:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`