Làm cách nào để chèn tham chiếu chéo trong trang reST / Sphinx vào tiêu đề phụ hoặc liên kết trong một trang khác trong cùng một bộ tài liệu?

Cụm từ "reST / Sphinx" làm cho phạm vi câu hỏi không rõ ràng. Đó là về reStructuredText nói chung và Sphinx, hay chỉ về reStructuredText như được sử dụng trong Sphinx (và không phải reStructuredText nói chung)? Tôi sẽ đề cập đến cả hai vì những người sử dụng RST có khả năng gặp phải cả hai trường hợp tại một số điểm:

Nhân sư

Bên cạnh các chỉ thị dành riêng cho miền có thể được sử dụng để liên kết với các thực thể khác nhau như các lớp ( :class:) còn có :ref:chỉ thị chung , được ghi lại ở đây . Họ đưa ra ví dụ này:

    .. _my-reference-label:

    Section to cross-reference
    --------------------------

    This is the text of the section.

    It refers to the section itself, see :ref:`my-reference-label`.

Mặc dù cơ chế siêu liên kết chung do RST cung cấp không hoạt động trong Sphinx, nhưng tài liệu khuyến cáo không nên sử dụng nó khi sử dụng Sphinx:

Sử dụng ref được khuyên dùng hơn là các liên kết reStructuredText tiêu chuẩn đến các phần (như Section title_) vì nó hoạt động trên các tệp, khi các tiêu đề của phần được thay đổi và cho tất cả các trình xây dựng hỗ trợ tham chiếu chéo.

RST, nói chung

Các công cụ chuyển đổi tệp RST sang HTML không nhất thiết phải có khái niệm thu thập . Đây là trường hợp chẳng hạn nếu bạn dựa vào github để chuyển đổi tệp RST sang HTML hoặc nếu bạn sử dụng một công cụ dòng lệnh như rst2html. Thật không may, các phương pháp khác nhau để sử dụng để có được kết quả mong muốn khác nhau tùy thuộc vào công cụ bạn đang sử dụng. Ví dụ: nếu bạn sử dụng rst2htmlvà bạn muốn tệp A.rstliên kết đến một phần có tên "Phần" trong tệp other.rstvà bạn muốn HTML cuối cùng hoạt động trong trình duyệt, thì tệp A.rstsẽ chứa:

`This <other.html#section>`__ is a reference to a section in another
file, which works with ``rst2html``. Unfortunately, it does not work
when the HTML is generated through github.

Bạn phải liên kết đến tệp HTML cuối cùng và bạn phải biết nội dung idđược cung cấp cho phần sẽ là gì. Nếu bạn muốn làm điều tương tự đối với tệp được cung cấp qua github:

`This <other.rst#section>`__ is a reference to a section in another
file, which works on github. Unfortunately, it does not work when you
use ``rst2html``.

Ở đây bạn cũng cần biết những gì idđược đưa ra cho phần. Tuy nhiên, bạn liên kết đến tệp RST vì chỉ khi truy cập tệp RST, HTML mới được tạo. (Tại thời điểm viết câu trả lời này, không được phép truy cập trực tiếp vào HTML.)

Một ví dụ hoàn chỉnh có sẵn ở đây .

Câu trả lời mới, hay hơn cho năm 2016!

Các phần mở rộng autosection cho phép bạn làm điều này một cách dễ dàng.

=============
Some Document
=============


Internal Headline
=================

sau đó, sau đó ...

===============
Some Other Doc
===============


A link-  :ref:`Internal Headline`

Tiện ích mở rộng này được tích hợp sẵn, vì vậy tất cả những gì bạn cần là chỉnh sửa conf.py

extensions = [
    .
    . other
    . extensions
    . already
    . listed
    .
    'sphinx.ext.autosectionlabel',
]

Điều duy nhất bạn phải cẩn thận là bây giờ bạn không thể sao chép các tiêu đề nội bộ trong bộ sưu tập tài liệu. (Đáng giá.)

Thí dụ:

Hey, read the :ref:`Installation:Homebrew` section.

đâu Homebrewlà một phần bên trong một tài liệu khác được đặt tên Installation.rst.

Điều này sử dụng tính năng tự động chọn , vì vậy sẽ cần phải chỉnh sửa config.pynhững điều sau:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True