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:
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.
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 .
RST, in General, itu berita yang mengecewakan!)
.. _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.
:ref:`Link title <lmy-reference-label>`
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.)
_page-title-learn-more). Agak menyebalkan, tapi saya masih suka mengandalkan autosection.
autosectionlabel_prefix_documentopsi 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:
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
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.
html/awalan