Menambahkan referensi silang ke subjudul atau jangkar di halaman lain

Jawaban:

207

Ekspresi "reST / Sphinx" membuat cakupan pertanyaan tidak jelas. Apakah ini tentang reStructuredText secara umum dan Sphinx, atau hanya tentang reStructuredText seperti yang digunakan di Sphinx (dan bukan reStructuredText secara umum)? Saya akan membahas keduanya karena orang yang menggunakan RST cenderung mengalami kedua kasus di beberapa titik:

Sphinx

Selain arahan khusus domain yang dapat digunakan untuk menautkan ke berbagai entitas seperti kelas ( :class:) ada :ref:arahan umum , yang didokumentasikan di sini . Mereka memberikan contoh ini:

    .. _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`.

Meskipun mekanisme hyperlink umum yang ditawarkan oleh RST berfungsi di Sphinx, dokumentasi merekomendasikan untuk tidak menggunakannya saat menggunakan Sphinx:

Penggunaan ref lebih disarankan daripada tautan reStructuredText standar ke bagian (seperti Section title_) karena berfungsi di seluruh file, saat judul bagian diubah, dan untuk semua pembuat yang mendukung referensi silang.

RST, secara Umum

Alat yang mengonversi file RST ke HTML tidak selalu memiliki pengertian koleksi . Ini adalah kasus misalnya jika Anda mengandalkan github untuk mengonversi file RST ke HTML atau jika Anda menggunakan alat baris perintah seperti rst2html. Sayangnya, berbagai metode yang digunakan untuk mendapatkan hasil yang diinginkan berbeda-beda, bergantung pada alat yang Anda gunakan. Misalnya, jika Anda menggunakan rst2htmldan Anda ingin file A.rstditautkan ke bagian bernama "Bagian" dalam file other.rstdan Anda ingin HTML final bekerja di browser, maka A.rstakan berisi:

`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.

Anda harus menautkan ke file HTML terakhir dan Anda harus tahu apa yang akan iddiberikan ke bagian tersebut. Jika Anda ingin melakukan hal yang sama untuk file yang disajikan melalui 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``.

Di sini juga Anda perlu mengetahui yang iddiberikan ke bagian tersebut. Namun, Anda menautkan ke file RST karena hanya setelah mengakses file RST itulah HTML dibuat. (Pada saat menulis jawaban ini, mengakses HTML secara langsung tidak diperbolehkan.)

Contoh lengkap tersedia di sini .

Louis
sumber
9
Jawaban yang jauh lebih baik daripada jawaban yang diterima oleh pemilik pertanyaan. (Terlepas dari kenyataan itu RST, in General, itu berita yang mengecewakan!)
dlm
1
Kerugian dari .. _my-reference-label:pendekatan Sphinx adalah yang my-reference-labelditampilkan di URL setelah #di link. Jadi, seseorang harus menggunakan nama label yang cantik. Selain itu, TOC selalu membuat #-link ke Section to cross-reference, dan dengan demikian satu berakhir dengan dua #-link berbeda ke bagian yang sama.
st12
3
Dan jika Anda ingin memberi tautan Anda nama yang berbeda, Anda selalu dapat menggunakan:ref:`Link title <lmy-reference-label>`
HyperActive
52

Jawaban baru yang lebih baik untuk tahun 2016!

The ekstensi autosection memungkinkan Anda melakukan ini dengan mudah.

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


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

lalu, nanti ...

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


A link-  :ref:`Internal Headline`

Ekstensi ini ada di dalamnya, jadi yang Anda butuhkan hanyalah mengedit conf.py

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

Satu-satunya hal yang harus Anda perhatikan adalah sekarang Anda tidak dapat menduplikasi berita utama internal di seluruh koleksi dokumen. (Setimpal.)

Adam Michael Wood
sumber
5
Sejak saya menulis jawaban ini, saya telah menemukan dalam praktiknya beberapa masalah dengan pendekatan ini. Pertama, mengganti nama bagian adalah masalah. Kedua, Anda sering memiliki judul bagian pendek seperti "Pelajari lebih lanjut" atau "ikhtisar" yang ingin Anda gunakan, yang tidak dapat Anda gunakan jika melakukannya. Solusi: tambahkan judul bagian ketika / jika Anda mengganti nama; tambahkan judul bagian untuk judul bagian yang pendek (seperti _page-title-learn-more). Agak menyebalkan, tapi saya masih suka mengandalkan autosection.
Adam Michael Wood
12
Sphinx 1.6 memperkenalkan autosectionlabel_prefix_documentopsi konfigurasi yang memungkinkan Anda menghindari masalah judul duplikat dengan memberi awalan pada setiap label bagian dengan nama dokumen asalnya.
PMOS
2
Ini solusi terbaik. Dan judul tautan dapat dengan mudah dimodifikasi :ref:`Link title <Internal Headline>`. Juga, Anda dapat menautkan langsung ke halaman (misalnya quickstart.rst) dengan:doc:`quickstart`
HyperActive
5

Contoh:

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

di mana Homebrewbagian di dalam dokumen berbeda bernama Installation.rst.

Ini menggunakan fitur autosection , jadi perlu mengedit config.pydengan yang berikut ini:

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
Jano
sumber
Di 2.0.0b1 mereka menambahkan autosectionlabel_maxdepth, jadi agar label otomatis berfungsi, Anda harus menyetel variabel itu ke> = 2. Juga, jika dokumen yang dihasilkan untuk subdir, seperti html, Anda harus awalan ref dengan namanya: :ref:'html/Installation:Homebrew'. Untuk alasan ini Anda mungkin ingin memilih beberapa nama dir yang umum, seperti generated, untuk membuat referensi kurang terlihat aneh ketika digunakan dengan format selain HTML. Karena itu, Anda sebaiknya 'Homebrew <Installation.html#Homebrew>'__menggunakan reST yang tepat dan tidak terikat dengan Sphinx.
Pugsley
Saya tidak membutuhkan html/awalan
Chris