Làm cách nào tôi có thể liên kết đến một phần của trang trong một nhân sư toctree

Question

Tôi có một trang .. toctree như một phần của trang nhân sư, bao gồm các liên kết tương đối đến các tệp rst khác trong gói của tôi. Làm thế nào tôi có thể bao gồm một liên kết đến một phần phụ của một trang nhất định, chứ không phải là toàn bộ trang?

Tôi mất một đâm vào

.. toctree:: 

    page#section 

Nhưng điều đó không làm việc. Bất kỳ trợ giúp là rất tốt.

Answer 1

Sau nhiều hackery, tôi đã đến giải pháp sau đây, nhưng trước tiên tôi phải nói rằng mục tiêu của tôi là:

1. có tiêu đề KHÔNG xuất hiện trong cơ thể nội dung
2. có tiêu đề xuất hiện trong TOC

Vì vậy, về cơ bản, liên kết từ TOC đến phần tùy ý nhưng vô hình của tài liệu.

Tôi cần điều này để có thể liên kết đến các phương pháp trong một số tài liệu mã nguồn được hiển thị bằng Sphinxcontrib PHPDomain - các phương pháp này tạo liên kết phần của riêng chúng, nhưng không được thêm vào TOC theo mặc định.

Bước 1:

Ở phía trên cùng của tập tin RST của bạn mà cần chức năng liên kết này, thêm một vai trò mới như vậy:

.. role:: hidden 
    :class: hidden 

Bước 2:

Một nơi nào đó trong nội dung, sử dụng vai trò này như vậy:

:hidden:`My Arbitrary Location` 
""""""""""""""""""""""""""""""" 

Bước 3:

Thêm CSS mới cho dự án (thường được thực hiện bằng cách thêm một file CSS vào _static, hoặc xác định một style sheet hoặc một cái gì đó như thế - xem this):

.rst-content .hidden { 
    display: none; 
} 

nav .hidden { 
    display: unset; 
} 

Điều này buộc tiêu đề được ẩn trong nội dung, nhưng được hiển thị trong TOC.

Sau đó, sử dụng lại vai trò khi cần thiết trong các tài liệu khác.

---

Lưu ý rằng nếu mục tiêu của bạn là để liên kết đến các địa điểm tùy ý trong tài liệu và vẫn có những tiêu đề xuất hiện trong nội dung, chỉ cần thay đổi CSS để định dạng các tiêu đề theo ý thích của bạn chứ không phải là ẩn chúng.

Answer 2

Khi tạo ToC, Nhân sư bao gồm tất cả các tiêu đề và tiêu đề phụ của tệp được tham chiếu trong chiều sâu cây được định cấu hình. Vì vậy, bạn có thể chỉ đơn giản là không bắt đầu trang với tiêu đề một và chèn tiêu đề tại thời điểm bạn muốn TOC để trỏ đến, ví dụ .:

.. _my-rst-file: 
**You can use bold print here if you want. This will not appear in the ToC** 
.. rubric:: Or the "rubric" directive 

And here some more text, normal font weight. 

Here comes the heading that will appear in the ToC 
"""""""""""""""""""""""""""""""""""""""""""""""""" 
And so on... 

Bạn cần phải bao gồm các tài liệu tham khảo trang trong TOC như bình thường. Vì vậy, trong TOC, bạn có:

.. toctree:: 

    my_rst_file 

Trong ví dụ của chúng tôi, kết quả xây dựng (HTML, PDF, bất cứ điều gì) sẽ chỉ có một tham chiếu đến Here comes the heading that will appear in the ToC trong TOC.