Bir reST / Sphinx sayfasına, aynı dokümantasyon setindeki başka bir sayfadaki bir alt başlığa veya bağlantıya nasıl çapraz referans eklenir?

"ReST / Sphinx" ifadesi sorunun kapsamını belirsizleştiriyor. Genel olarak reStructuredText ve Sphinx ile mi ilgili , yoksa yalnızca Sphinx'te kullanılan reStructuredText ile mi ilgili (ve genel olarak reStructuredText değil)? Her ikisini de ele alacağım çünkü RST kullanan kişiler bir noktada her iki durumla da karşılaşacaklar:

Sfenks

Sınıflar ( :class:) gibi çeşitli varlıklara bağlanmak için kullanılabilecek alana özgü yönergelerin yanı sıra, burada:ref: belgelenen genel bir yönerge de vardır . Bu örneği veriyorlar:

    .. _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 tarafından sunulan genel köprü oluşturma mekanizması Sphinx'te çalışsa da, dokümantasyon Sphinx'i kullanırken bunu kullanmamanızı tavsiye ediyor:

Ref kullanımı, bölümlere olan standart reStructuredText bağlantıları yerine ( Section title_ gibi ) tavsiye edilir çünkü dosyalar arasında, bölüm başlıkları değiştirildiğinde ve çapraz referansları destekleyen tüm oluşturucular için çalışır.

RST, Genel olarak

RST dosyalarını HTML'ye dönüştüren araçlar mutlaka bir koleksiyon kavramına sahip değildir . Örneğin, RST dosyalarını HTML'ye dönüştürmek için github'a güveniyorsanız veya gibi bir komut satırı aracı kullanıyorsanız, durum budur rst2html. Ne yazık ki, istenen sonucu elde etmek için kullanılacak çeşitli yöntemler, kullandığınız araca bağlı olarak değişir. Örneğin, rst2htmlfile kullanıyorsanız ve dosyada A.rst"Bölüm" adlı bir bölüme bağlanmak other.rstistiyorsanız ve son HTML'nin bir tarayıcıda çalışmasını A.rstistiyorsanız , o zaman şunları içerir:

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

Son HTML dosyasına bağlanmanız ve idbölüme verilenin ne olacağını bilmeniz gerekir. Aynı şeyi github üzerinden sunulan bir dosya için yapmak istiyorsanız:

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

Burada da idbölüme verilenleri bilmeniz gerekiyor . Ancak, RST dosyasına bağlantı oluşturursunuz, çünkü HTML yalnızca RST dosyasına erişildiğinde oluşturulur. (Bu cevabı yazarken, HTML'ye doğrudan erişime izin verilmez.)

Tam bir örnek burada mevcuttur .

2016 için yeni, daha iyi yanıt!

Otomatik bölüm uzantısı bunu kolayca yapmanızı sağlar.

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


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

daha sonra...

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


A link-  :ref:`Internal Headline`

Bu uzantı yerleşiktir, bu nedenle tek ihtiyacınız olan şey düzenlemek conf.py

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

Dikkat etmeniz gereken tek şey, artık belge koleksiyonunda dahili başlıkları kopyalayamayacağınızdır. (Buna değer.)

Misal:

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

Homebrewadlı farklı bir belgenin içindeki bir bölüm nerede Installation.rst.

Bu, otomatik algılama özelliğini kullanır , bu nedenle config.pyaşağıdakilerle düzenlemeniz gerekir :

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