จะแทรกการอ้างอิงโยงในหน้า reST / Sphinx ไปยังส่วนหัวย่อยหรือจุดยึดในหน้าอื่นในชุดเอกสารเดียวกันได้อย่างไร

นิพจน์ "reST / Sphinx" ทำให้ขอบเขตของคำถามไม่ชัดเจน มันเกี่ยวกับ reStructuredText โดยทั่วไปและ Sphinx หรือเฉพาะเกี่ยวกับ reStructuredText ที่ใช้ใน Sphinx (และไม่ใช่ reStructuredText โดยทั่วไป)? ฉันจะกล่าวถึงทั้งสองอย่างเนื่องจากผู้ที่ใช้ RST มีแนวโน้มที่จะพบเจอทั้งสองกรณีในบางประเด็น:

สฟิงซ์

นอกจากสั่งโดเมนเฉพาะที่สามารถใช้ในการเชื่อมโยงไปยังหน่วยงานต่าง ๆ เช่นการเรียน ( :class:) มีนายพล:ref:สั่งการบันทึกไว้ที่นี่ พวกเขายกตัวอย่างนี้:

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

แม้ว่ากลไกการเชื่อมโยงหลายมิติทั่วไปที่นำเสนอโดย RST จะใช้งานได้ใน Sphinx เอกสารแนะนำไม่ให้ใช้เมื่อใช้ Sphinx:

แนะนำให้ใช้การอ้างอิงผ่านลิงก์ reStructuredText มาตรฐานไปยังส่วนต่างๆ (เช่นSection title_) เนื่องจากทำงานข้ามไฟล์เมื่อมีการเปลี่ยนแปลงส่วนหัวและสำหรับตัวสร้างทั้งหมดที่รองรับการอ้างอิงข้าม

RST โดยทั่วไป

เครื่องมือที่แปลงไฟล์ RST เพื่อ HTML ไม่จำเป็นต้องมีความคิดของคอลเลกชัน นี่เป็นกรณีตัวอย่างเช่นหากคุณใช้ github ในการแปลงไฟล์ RST เป็น HTML หรือหากคุณใช้เครื่องมือบรรทัดคำสั่งเช่นrst2html. น่าเสียดายที่วิธีการต่างๆที่จะใช้เพื่อให้ได้ผลลัพธ์ที่ต้องการนั้นแตกต่างกันไปขึ้นอยู่กับเครื่องมือที่คุณใช้ ตัวอย่างเช่นหากคุณใช้rst2htmlและต้องการให้ไฟล์A.rstเชื่อมโยงไปยังส่วนที่ชื่อ "Section" ในไฟล์other.rstและคุณต้องการให้ HTML สุดท้ายทำงานในเบราว์เซอร์A.rstจะประกอบด้วย:

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

คุณต้องเชื่อมโยงไปยังไฟล์ HTML สุดท้ายและคุณต้องรู้ว่าส่วนที่idกำหนดจะเป็นอย่างไร หากคุณต้องการทำเช่นเดียวกันสำหรับไฟล์ที่ให้บริการผ่าน 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``.

ที่นี่คุณจำเป็นต้องรู้สิ่งที่idกำหนดให้กับส่วนนี้ด้วย อย่างไรก็ตามคุณเชื่อมโยงไปยังไฟล์ RST เนื่องจากมีการเข้าถึงไฟล์ RST ที่สร้าง HTML เท่านั้น (ในขณะที่เขียนคำตอบนี้ไม่อนุญาตให้เข้าถึง HTML โดยตรง)

เป็นตัวอย่างที่สมบูรณ์แบบสามารถใช้ได้ที่นี่

ใหม่ตอบโจทย์ปี 2559 ดีกว่า!

ขยาย autosectionช่วยให้คุณสามารถทำเช่นนี้ได้อย่างง่ายดาย

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


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

จากนั้นต่อมา ...

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


A link-  :ref:`Internal Headline`

ส่วนขยายนี้มีอยู่ในตัวดังนั้นคุณต้องแก้ไขทั้งหมด conf.py

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

สิ่งเดียวที่คุณต้องระวังคือตอนนี้คุณไม่สามารถทำซ้ำพาดหัวข่าวภายในในคอลเล็กชันเอกสารได้ (คุ้มมาก)

ตัวอย่าง:

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

ซึ่งเป็นส่วนที่อยู่ภายในเอกสารที่แตกต่างกันชื่อHomebrewInstallation.rst

สิ่งนี้ใช้คุณสมบัติการตรวจสอบอัตโนมัติดังนั้นจะต้องแก้ไขconfig.pyดังต่อไปนี้:

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