Bagaimana cara memasukkan referensi silang di halaman reST / Sphinx ke sub-header atau jangkar di halaman lain dalam set dokumentasi yang sama?
python-sphinx
restructuredtext
Sue Walsh
sumber
sumber
Jawaban:
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:Meskipun mekanisme hyperlink umum yang ditawarkan oleh RST berfungsi di Sphinx, dokumentasi merekomendasikan untuk tidak menggunakannya saat menggunakan Sphinx:
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 menggunakanrst2html
dan Anda ingin fileA.rst
ditautkan ke bagian bernama "Bagian" dalam fileother.rst
dan Anda ingin HTML final bekerja di browser, makaA.rst
akan berisi:Anda harus menautkan ke file HTML terakhir dan Anda harus tahu apa yang akan
id
diberikan ke bagian tersebut. Jika Anda ingin melakukan hal yang sama untuk file yang disajikan melalui github:Di sini juga Anda perlu mengetahui yang
id
diberikan 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 .
sumber
RST, in General
, itu berita yang mengecewakan!).. _my-reference-label:
pendekatan Sphinx adalah yangmy-reference-label
ditampilkan di URL setelah#
di link. Jadi, seseorang harus menggunakan nama label yang cantik. Selain itu, TOC selalu membuat#
-link keSection to cross-reference
, dan dengan demikian satu berakhir dengan dua#
-link berbeda ke bagian yang sama.:ref:`Link title <lmy-reference-label>`
Jawaban baru yang lebih baik untuk tahun 2016!
The ekstensi autosection memungkinkan Anda melakukan ini dengan mudah.
lalu, nanti ...
Ekstensi ini ada di dalamnya, jadi yang Anda butuhkan hanyalah mengedit
conf.py
Satu-satunya hal yang harus Anda perhatikan adalah sekarang Anda tidak dapat menduplikasi berita utama internal di seluruh koleksi dokumen. (Setimpal.)
sumber
_page-title-learn-more
). Agak menyebalkan, tapi saya masih suka mengandalkan autosection.autosectionlabel_prefix_document
opsi konfigurasi yang memungkinkan Anda menghindari masalah judul duplikat dengan memberi awalan pada setiap label bagian dengan nama dokumen asalnya.:ref:`Link title <Internal Headline>`
. Juga, Anda dapat menautkan langsung ke halaman (misalnya quickstart.rst) dengan:doc:`quickstart`
Contoh:
di mana
Homebrew
bagian di dalam dokumen berbeda bernamaInstallation.rst
.Ini menggunakan fitur autosection , jadi perlu mengedit
config.py
dengan yang berikut ini:sumber
autosectionlabel_maxdepth
, jadi agar label otomatis berfungsi, Anda harus menyetel variabel itu ke> =2
. Juga, jika dokumen yang dihasilkan untuk subdir, sepertihtml
, Anda harus awalan ref dengan namanya::ref:'html/Installation:Homebrew'
. Untuk alasan ini Anda mungkin ingin memilih beberapa nama dir yang umum, sepertigenerated
, 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.html/
awalan