Adicionar uma referência cruzada a um subtítulo ou âncora em outra página

Respostas:

207

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 .

Louis
fonte
9
Resposta muito melhor do que a aceita pelo proprietário da pergunta. (Apesar do fato de que RST, in General, foram notícias decepcionantes!)
dlm
1
Uma desvantagem da .. _my-reference-label:abordagem Sphinx é que my-reference-labelé mostrada na URL depois #do link. Portanto, deve-se usar nomes de rótulos bonitos. Além disso, o TOC sempre cria um #-link para Section to cross-referencee, portanto, termina com dois #-links diferentes para a mesma seção.
st12
3
E se você quiser dar ao seu link um nome diferente, você sempre pode usar:ref:`Link title <lmy-reference-label>`
HyperActive
52

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

Adam Michael Wood
fonte
5
Desde que escrevi esta resposta, descobri na prática alguns problemas com essa abordagem. Primeiro, a renomeação da seção é um problema. Em segundo lugar, você costuma ter títulos de seção curtos como "Saiba mais" ou "visão geral" que deseja usar, o que não será possível se estiver fazendo isso. Solução: adicione o título da seção quando / se você renomear; adicione um título de seção para os títulos de seção curtos (como _page-title-learn-more). É um pouco chato, mas ainda gosto de confiar principalmente na autosecção.
Adam Michael Wood
12
O Sphinx 1.6 introduz a autosectionlabel_prefix_documentopção de configuração que permite evitar o problema de título duplicado, prefixando cada etiqueta de seção com o nome do documento de onde vem.
pmos
2
essa é a melhor solução. E o título do link pode ser facilmente modificado com :ref:`Link title <Internal Headline>`. Além disso, você pode criar um link direto para uma página (quickstart.rst, por exemplo) com:doc:`quickstart`
HyperActive
5

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
Jano
fonte
No 2.0.0b1 eles adicionaram autosectionlabel_maxdepth, portanto, para autosectionlabel funcionar, você deve definir essa variável como> = 2. Além disso, se docs são gerados para subdir, como html, você deve prefixar refs com seu nome: :ref:'html/Installation:Homebrew'. Por esta razão, você pode querer escolher algum nome de diretório genérico, como generated, para tornar a aparência de referência menos estranha quando usado com formatos diferentes de HTML. Por causa disso, você pode muito bem 'Homebrew <Installation.html#Homebrew>'__usar o reST adequado e não estar vinculado ao Sphinx.
Pugsley
Não html/precisei do prefixo
Chris,