Dodanie odsyłacza do nagłówka lub kotwicy na innej stronie

Odpowiedzi:

207

Wyrażenie „reST / Sphinx” sprawia, że ​​zakres pytania jest niejasny. Czy chodzi o reStructuredText w ogóle i Sphinx, czy tylko o reStructuredText używane w Sphinx (a nie o reStructuredText w ogóle)? Omówię oba, ponieważ ludzie używający RST prawdopodobnie napotkają w pewnym momencie oba przypadki:

Sfinks

Oprócz dyrektyw specyficznych dla domeny, które mogą być używane do łączenia się z różnymi jednostkami, takimi jak class ( :class:), istnieje :ref:dyrektywa ogólna , udokumentowana tutaj . Podają ten przykład:

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

Chociaż ogólny mechanizm hiperłączy oferowany przez RST działa w Sphinx, dokumentacja odradza używanie go podczas korzystania z Sphinx:

Używanie ref jest zalecane zamiast standardowych linków reStructuredText do sekcji (takich jak Section title_), ponieważ działa ono w różnych plikach, gdy zmieniane są nagłówki sekcji i dla wszystkich kreatorów, które obsługują odsyłacze.

RST, ogólnie

Narzędzia konwertujące pliki RST na HTML niekoniecznie mają pojęcie kolekcji . Dzieje się tak na przykład, jeśli korzystasz z github do konwersji plików RST do HTML lub jeśli używasz narzędzia wiersza poleceń, takiego jak rst2html. Niestety, różne metody uzyskiwania pożądanego rezultatu różnią się w zależności od używanego narzędzia. Na przykład, jeśli używasz rst2htmli chcesz, aby plik A.rstłączył się z sekcją o nazwie „Sekcja” w pliku other.rsti chcesz, aby ostateczny kod HTML działał w przeglądarce, A.rstpowinien zawierać:

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

Musisz idpodać link do ostatecznego pliku HTML i wiedzieć, jakie będzie dane sekcji. Jeśli chcesz zrobić to samo dla pliku udostępnianego przez 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``.

Tutaj również musisz znać idpodane w sekcji. Jednak łączysz się z plikiem RST, ponieważ dopiero po uzyskaniu dostępu do pliku RST tworzony jest kod HTML. (W chwili pisania tej odpowiedzi bezpośredni dostęp do kodu HTML nie jest dozwolony).

Pełny przykład jest dostępny tutaj .

Louis
źródło
9
O wiele lepsza odpowiedź niż ta, którą zaakceptował właściciel pytania. (Mimo tego RST, in Generalrozczarowująca wiadomość!)
dlm
1
Wadą .. _my-reference-label:podejścia Sphinx jest to, że my-reference-labeljest wyświetlany w adresie URL po #linku. Trzeba więc używać ładnych nazw etykiet. Ponadto spis treści zawsze tworzy #-link do Section to cross-reference, a więc kończy się to dwoma różnymi #-linkami do tej samej sekcji.
12
4
A jeśli chcesz nadać swojemu :ref:`Link title <lmy-reference-label>`
linkowi
53

Nowa, lepsza odpowiedź na rok 2016!

Przedłużenie sekcji opryskiwacza pozwala to zrobić łatwo.

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


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

potem, później ...

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


A link-  :ref:`Internal Headline`

To rozszerzenie jest wbudowane, więc wszystko, czego potrzebujesz, to edycja conf.py

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

Jedyną rzeczą, na którą musisz uważać, jest to, że nie możesz teraz powielać nagłówków wewnętrznych w całej kolekcji dokumentów. (Warto było.)

Adam Michael Wood
źródło
5
Odkąd napisałem tę odpowiedź, odkryłem w praktyce kilka problemów związanych z tym podejściem. Po pierwsze, problemem jest zmiana nazwy sekcji. Po drugie, często masz krótkie tytuły sekcji, takie jak „Dowiedz się więcej” lub „przegląd”, których chcesz użyć, których nie możesz, jeśli to robisz. Rozwiązanie: dodaj tytuł sekcji, gdy / jeśli zmienisz nazwę; dodaj tytuł sekcji dla krótkich tytułów sekcji (takich jak _page-title-learn-more). To trochę denerwujące, ale nadal lubię polegać głównie na autosekcji.
Adam Michael Wood
12
Sphinx 1.6 wprowadza autosectionlabel_prefix_documentopcję konfiguracji, która pozwala uniknąć problemu z powielonymi nagłówkami, poprzedzając każdą etykietę sekcji nazwą dokumentu, z którego pochodzi.
pmos
2
To najlepsze rozwiązanie. Tytuł linku można łatwo zmodyfikować za pomocą :ref:`Link title <Internal Headline>`. Możesz również utworzyć łącze bezpośrednio do strony (na przykład :doc:`quickstart`
quickstart.rst
5

Przykład:

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

gdzie Homebrewjest sekcja wewnątrz innego dokumentu o nazwie Installation.rst.

Korzysta z funkcji autosekcji , więc będzie trzeba edytować config.pyz następującymi elementami :

extensions = [
    'sphinx.ext.autosectionlabel'
]
autosectionlabel_prefix_document = True
Jano
źródło
W 2.0.0b1 dodali autosectionlabel_maxdepth, więc aby autosectionlabel działał, musisz ustawić tę zmienną na> = 2. Ponadto, jeśli są generowane docs do podkatalogu, podobnie html, należy poprzedzić bibl z nazwy: :ref:'html/Installation:Homebrew'. Z tego powodu możesz wybrać ogólną nazwę katalogu, na przykład generated, aby referencje były mniej dziwne, gdy są używane z formatami innymi niż HTML. Z tego powodu możesz równie dobrze 'Homebrew <Installation.html#Homebrew>'__użyć odpowiedniego reST i nie być przywiązanym do Sfinksa.
Pugsley
Nie potrzebowałem html/prefiksu
Chris