我可以在同一文件页面中引用另一个第一个文档中的 header 并保持 header 吗？

Question

我正在使用 sphinx 并创建了多个第一个文件来组织我的文档。我使用 .. include:: <filepath/filename.rst> 将多个第一个文件包含到一个配置文件中，但是当使用 :ref:`<reference>` 时，这会保留文件名 header 标签，但是当我单击 link 时，它会隔离页面但是我希望它滚动到同一页中的参考。当我使用 <reference>_ 时，这将滚动到同一文档中的区域，但不再保留 header 标签。有没有一种方法可以保留参考 header 标签并在同一页面内滚动，同时仍将文档保留在不同的文件中？

index.rst

Welcome to testing's documentation!
===================================

.. toctree::
    :maxdepth: 2
    :caption: Contents:

    test/config

test/config.rst

.. title:

Hello moto
==========

Using ref maintains header

* :ref:`ref-nested`

Using underscore doesn't maintain header

- nested_

.. include:: nested_test/file.rst

.. include:: nested_test/anotherfile.rst

test/anotherdir/file.rst

.. _nested:

I'm a nested header
-------------------

Hi I'm the created nested header

test/anotherdir/anotherfile.rst

.. _ref-nested:

I'm the ref nested header
-------------------------

I'm the ref nested header

正如您在下面看到的，第一个 link(:ref:) 保留给定的 header，但如果您单击它，它将转到一个单独的页面。第二个 link 不保留 header 给出但使用实际参考，但如果单击它，它将保留在同一页面上并在文档中移动。

下面是两张图片，当使用 :ref: 时，它会将页面加载为单独的第一个文件。

我希望 link 像在文档中一样向下滚动。

Answer 1

如果我明白你想要什么，你可以将目标及其 header 从包含文件移动到主文件中。

.. title:

Hello moto
==========

Using ref maintains header

* :ref:`ref-nested`

Using underscore doesn't maintain header

- nested_

.. _nested:

I'm a nested header
-------------------

.. include:: nested_test/file.rst

.. _ref-nested:

I'm the ref nested header
-------------------------

.. include:: nested_test/anotherfile.rst

这有一个额外的好处，如果您将包含的文件包含在多个文件中，那么您可以指定一个唯一的目标并避免 Sphinx 错误。

Answer 2

我在此处的另一个堆栈溢出问题上找到了我想要的答案。如果它在同一个文件中，我不必使用 include 创建引用，我可以引用标题本身。请参阅 link 并查看@Baleb 的回答。

How to make an internal link to a heading in sphinx restructuredtext without creating arbitrary labels?

我可以在同一文件页面中引用另一个第一个文档中的 header 并保持 header 吗？

Can I reference a header from another rst document and maintain the header while staying in the same file page?

restructuredtext

python-sphinx