Como inserir uma referência cruzada em uma página reST / Sphinx para um subcabeçalho ou âncora em outra página no mesmo conjunto de documentação?

A expressão "reST / Sphinx" torna o escopo da questão pouco claro. É sobre reStructuredText em geral e Sphinx, ou apenas sobre reStructuredText como usado em Sphinx (e não reStructuredText em geral)? Vou cobrir ambos, já que as pessoas que usam RST provavelmente se depararão com os dois casos em algum momento:

Esfinge

Além das diretivas específicas do domínio que podem ser usadas para vincular a várias entidades como classes ( :class:), há a :ref:diretiva geral , documentada aqui . Eles dão este exemplo:

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

Embora o mecanismo geral de hiperlinks oferecido pelo RST funcione no Sphinx, a documentação não recomenda usá-lo ao usar o Sphinx:

O uso de ref é recomendado em vez de links reStructuredText padrão para seções (como Section title_) porque ele funciona em arquivos, quando os cabeçalhos de seção são alterados e para todos os construtores que suportam referências cruzadas.

RST, em geral

As ferramentas que convertem arquivos RST em HTML não necessariamente têm uma noção de coleção . Este é o caso, por exemplo, se você confia no github para converter arquivos RST em HTML ou se você usa uma ferramenta de linha de comando como rst2html. Infelizmente, os vários métodos a serem usados ​​para obter o resultado desejado variam de acordo com a ferramenta que você está usando. Por exemplo, se você usa rst2htmle deseja que o arquivo A.rstseja vinculado a uma seção chamada "Seção" no arquivo other.rste deseja que o HTML final funcione em um navegador, então A.rstconteria:

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

Você tem que vincular ao arquivo HTML final e saber qual será o iddado à seção. Se você quiser fazer o mesmo para um arquivo veiculado por meio do 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``.

Aqui também você precisa saber o iddado à seção. No entanto, você vincula ao arquivo RST porque é apenas ao acessar o arquivo RST que o HTML é criado. (No momento em que escrevo esta resposta, acessar o HTML diretamente não é permitido.)

Um exemplo completo está disponível aqui .

Nova e melhor resposta para 2016!

A extensão de autosecção permite que você faça isso facilmente.

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


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

então, depois ...

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


A link-  :ref:`Internal Headline`

Esta extensão é integrada, então tudo que você precisa é editar conf.py

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

A única coisa com que você precisa ter cuidado é que agora você não pode duplicar títulos internos em toda a coleção de documentos. (Vale a pena.)

Exemplo:

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

onde Homebrewé uma seção dentro de um documento diferente nomeado Installation.rst.

Isso usa o recurso de autosecção , portanto, será necessário editar config.pycom o seguinte:

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