एक अन्य पृष्ठ में एक सबहेडिंग या एंकर के लिए एक क्रॉस-संदर्भ जोड़ना

Question

एक ही दस्तावेज़ीकरण सेट में किसी अन्य पृष्ठ में किसी सब-हेडर या एंकर के लिए एक reST / Sphinx पृष्ठ में क्रॉस-संदर्भ कैसे डालें?

Comments

स्फिंक्स डॉक्यूमेंट में इंटरनल हाइपर लिंक बनाने

— Saullo GP Castro

Answer 1

"रेस्ट / स्फिंक्स" अभिव्यक्ति प्रश्न के दायरे को अस्पष्ट बना देती है। यह सामान्य और स्फिंक्स में reStructuredText के बारे में है , या केवल 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 द्वारा पेश किया जाने वाला सामान्य हाइपरलिंकिंग तंत्र स्फिंक्स में काम करता है, लेकिन प्रलेखन SININX का उपयोग करते समय इसका उपयोग करने के खिलाफ अनुशंसा करता है:

Ref का उपयोग मानक reStructuredText लिंक पर सेक्शनों (जैसे Section title_) से अधिक करने की सलाह दी जाती है क्योंकि यह फाइलों में काम करता है, जब सेक्शन के हेडिंग बदले जाते हैं, और क्रॉस-रेफरेंस का समर्थन करने वाले सभी बिल्डरों के लिए।

जनरल में आर.एस.टी.

जरूरी उपकरण जो आरएसटी फाइलों को एचटीएमएल में बदलते हैं, जरूरी नहीं कि संग्रह की धारणा हो । उदाहरण के लिए यह मामला है अगर आप जीएसटी पर भरोसा करते हुए आरएसटी फ़ाइलों को एचटीएमएल में कनवर्ट करते हैं या यदि आप कमांड लाइन टूल का उपयोग करते हैं जैसे rst2html। दुर्भाग्यवश, वांछित परिणाम प्राप्त करने के लिए उपयोग करने के लिए विभिन्न तरीके किस उपकरण का उपयोग कर रहे हैं, इसके आधार पर भिन्न होते हैं। उदाहरण के लिए, यदि आप उपयोग करते हैं rst2htmlऔर आप फ़ाइल में A.rst"सेक्शन" नामक अनुभाग से लिंक 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 तक सीधे पहुँच की अनुमति नहीं है।)

एक पूरा उदाहरण यहां उपलब्ध है ।

Comments

प्रश्न के स्वामी द्वारा स्वीकार किए जाने वाले से बेहतर उत्तर। (इस तथ्य के बावजूद RST, in General, निराशाजनक खबर थी!)

— dlm

स्फिंक्स .. _my-reference-label:दृष्टिकोण का एक नुकसान यह है कि लिंक के my-reference-labelबाद URL में दिखाया गया है #। तो एक सुंदर लेबल नाम का उपयोग करना चाहिए। इसके अलावा, टीओसी हमेशा एक बनाता है #के लिए -लिंक Section to cross-reference, और इस तरह एक दो अलग अलग के साथ समाप्त होता है #एक ही अनुभाग के लिए -links।

— st12

और अगर आप अपने लिंक को एक अलग नाम देना चाहते हैं तो आप हमेशा इस्तेमाल कर सकते हैं:ref:`Link title <lmy-reference-label>`

— हाइपरऐक्टिव

Answer 2

2016 के लिए नया, बेहतर जवाब!

Autosection विस्तार आप आसानी से कर सकते हैं।

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


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

फिर बाद में...

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


A link-  :ref:`Internal Headline`

यह एक्सटेंशन बिल्ट-इन है, इसलिए आपको केवल एडिट करना है conf.py

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

केवल एक चीज जिससे आपको सावधान रहना है कि अब आप डॉक संग्रह में आंतरिक सुर्खियों की नकल नहीं कर सकते। (इसके लायक।)

Comments

जब से मैंने यह उत्तर लिखा है, मैंने इस दृष्टिकोण के साथ कुछ समस्याओं का अभ्यास किया है। सबसे पहले, अनुभाग का नाम बदलना एक समस्या है। दूसरा, आपके पास अक्सर "अधिक जानें" या "अवलोकन" जैसे छोटे खंड शीर्षक होते हैं, जिनका आप उपयोग करना चाहते हैं, जो आप ऐसा नहीं कर सकते। समाधान: जब आप का नाम बदलें / तब अनुभाग शीर्षक जोड़ें; लघु खंड शीर्षकों के लिए एक अनुभाग शीर्षक जोड़ें (जैसे _page-title-learn-more)। यह थोड़ा परेशान करने वाला है, लेकिन मुझे अभी भी ज्यादातर ऑटो रिक्शा पर भरोसा करना पसंद है।

— एडम माइकल वुड

स्फिंक्स 1.6 autosectionlabel_prefix_documentविन्यास विकल्प का परिचय देता है जो आपको प्रत्येक अनुभाग लेबल को उस दस्तावेज़ के नाम के साथ प्रीफ़िक्स करके डुप्लिकेट हेडलाइन समस्या से बचने देता है।

— pmos

यह सबसे अच्छा उपाय है। और लिंक शीर्षक को आसानी से संशोधित किया जा सकता है :ref:`Link title <Internal Headline>`। इसके अलावा, आप सीधे एक पेज (उदाहरण के लिए quickstart.rst) के साथ लिंक कर सकते हैं:doc:`quickstart`

— हाइपरएक्टिव ऑक्ट

Answer 3

उदाहरण:

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

Homebrewनाम के एक अलग दस्तावेज़ के अंदर एक खंड कहाँ है Installation.rst।

यह ऑटोसनेशन फीचर का उपयोग करता है , इसलिए इसे config.pyनिम्नलिखित के साथ संपादित करना होगा:

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

Comments

2.0.0b1 में उन्होंने जोड़ा है autosectionlabel_maxdepth, इसलिए ऑटोसेंक्लाबेल काम करने के लिए आपको उस चर को> = पर सेट करना होगा 2। इसके अलावा, अगर डॉक्स सबडिर को जनरेट किए जाते हैं, जैसे html, आपको इसके नाम के साथ उपसर्ग रेफरी होना चाहिए :ref:'html/Installation:Homebrew':। इस कारण से आप कुछ सामान्य dir नाम चुनना चाह सकते हैं, जैसे generated, HTML के अलावा अन्य स्वरूपों के साथ उपयोग करने पर Refs को कम अजीब दिखना। इस वजह से, आप 'Homebrew <Installation.html#Homebrew>'__उचित रेस्ट का उपयोग करने और स्फिंक्स से बंधे नहीं होने के साथ जा सकते हैं।

— पग्सले

मुझे html/उपसर्ग की आवश्यकता नहीं थी

— क्रिस