Jak wstawić odsyłacz na stronie reST / Sphinx do nagłówka podrzędnego lub kotwicy na innej stronie w tym samym zestawie dokumentacji?

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 .

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

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