如何使用部分 ID 引用项目中的另一个页面？
How to reference another page in project with section ID?
工作正常，只要我不需要特定部分 - 这似乎工作：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>` （没有）
如果您的目标是 cross-referencing 内部项目，我认为使用 intersphinx 不是一个好方法。
此时必须注意：当使用 automodule 或 autoclass 等 autodoc 指令之一时，Python 对象被放置在 Sphinx 索引中并且可以cross-referenced.
但这提出了一个问题：如何cross-reference ReST sections？它被认为是 arbitrary location，因为它们不是对象，并且它们不会通过 autodoc 指令（或通过 .rst 中的 py 域声明）插入到 Sphinx 索引中。
那么，在那种情况下，有 4 个主要选项可供考虑（最后一个可能最不明显，因此也是最重要的）：
- 使用 ReST hyperlink targets directly above the section。
- 使用 Python 域引用直接指向该部分下方的 autodoc 指令。
- 如果该部分位于
.rst 文件的顶部，请使用 cross-reference to the document。
最后但同样重要的是：
- 假设您有 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 索引中！！！为什么那么重要？？因为您可以 cross-reference 将其作为 Python 模块（毕竟包是模块），而不必 cross-reference 将其作为文档或部分。这使您的文档、索引和 cross-referencing...
整体保持一致
最终结果？你永远不会看到 HTML 或锚点..!! Sphinx manages/generates/indexes 所有这一切都为您服务。这就是你真正想要的。一个完整的抽象层。
有人提出异议：
- “您正在将 Sphinx/ReST 放入您的 Python 文档字符串中（人们不知道如何阅读它）。”
很容易解决，将纯英文放在Docstring中，将ReST/Sphinx语法放在.rst文件中（autodoc将加入部分）。
- 其他人会反对：“我想要 HTML 在我的 ReST 中！”
果然如此，但是每当您编辑或重构某些内容时，它注定会成为一种痛苦。谁说正常的 Python/ReST 开发人员看你的东西就知道什么 - 或者想看 - HTML 或锚点？
所以最合理的分离是沿着这些路线进行的。
关于使用重复的目标名称：
没有理由使用重复的目标名称。从您的 IDE 完成的重构最好由唯一的目标名称提供。如果您决定移动 ReST 部分，上面的目标将随之移动。
.. _this_section_without_duplicate_name:
*****************
Your ReST section
*****************
:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`
不需要锚点。更干净光滑。
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>`（没有）
如果您的目标是 cross-referencing 内部项目，我认为使用 intersphinx 不是一个好方法。
此时必须注意：当使用 automodule 或 autoclass 等 autodoc 指令之一时，Python 对象被放置在 Sphinx 索引中并且可以cross-referenced.
但这提出了一个问题：如何cross-reference ReST sections？它被认为是 arbitrary location，因为它们不是对象，并且它们不会通过 autodoc 指令（或通过 .rst 中的 py 域声明）插入到 Sphinx 索引中。
那么，在那种情况下，有 4 个主要选项可供考虑（最后一个可能最不明显，因此也是最重要的）：
- 使用 ReST hyperlink targets directly above the section。
- 使用 Python 域引用直接指向该部分下方的 autodoc 指令。
- 如果该部分位于
.rst文件的顶部，请使用 cross-reference to the document。
最后但同样重要的是：
- 假设您有 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 索引中！！！为什么那么重要？？因为您可以 cross-reference 将其作为 Python 模块（毕竟包是模块），而不必 cross-reference 将其作为文档或部分。这使您的文档、索引和 cross-referencing...
最终结果？你永远不会看到 HTML 或锚点..!! Sphinx manages/generates/indexes 所有这一切都为您服务。这就是你真正想要的。一个完整的抽象层。
有人提出异议：
- “您正在将 Sphinx/ReST 放入您的 Python 文档字符串中（人们不知道如何阅读它）。”
很容易解决，将纯英文放在Docstring中，将ReST/Sphinx语法放在.rst文件中（autodoc将加入部分）。
- 其他人会反对：“我想要 HTML 在我的 ReST 中！”
果然如此，但是每当您编辑或重构某些内容时，它注定会成为一种痛苦。谁说正常的 Python/ReST 开发人员看你的东西就知道什么 - 或者想看 - HTML 或锚点？
所以最合理的分离是沿着这些路线进行的。
关于使用重复的目标名称：
没有理由使用重复的目标名称。从您的 IDE 完成的重构最好由唯一的目标名称提供。如果您决定移动 ReST 部分，上面的目标将随之移动。
.. _this_section_without_duplicate_name:
*****************
Your ReST section
*****************
:ref:`NICE_USER_DISPLAY_NAME <_this_section_without_duplicate_name>`
不需要锚点。更干净光滑。