web-dev-qa-db-ja.com

別のページの小見出しまたはアンカーへの相互参照の追加

ReST/Sphinxページの相互参照を、同じドキュメントセット内の別のページのサブヘッダーまたはアンカーに挿入する方法

python-sphinxrestructuredtext
86
Sue Walsh

この回答は無視してください、うまくいきません： ルイからの回答 、以下

アンカーの場合、次のように「短い」アンカー名を定義できます。

.. _ShortAnchor:

Target Header goes here
=======================

Some text.

そのヘッダーを参照するには：

For more details, see ShortAnchor_.

これにより、ShortAnchorがヘッダーのフルネームにまで拡張されることに注意してください。

次のような完全なヘッダー名を使用することもできます。

See `Target Header goes here`_ chapter.

しかし、これはヘッダーテキストの変更に起因するエラーです。

これはすべて、1つの最終ドキュメントの一部である複数のソースファイルで機能します。

12
Jan Vlcinsky

「reST/Sphinx」という表現は、質問の範囲を不明確にします。一般的なreStructuredTextについてですかandSphinx、またはonlyreStructuredTextSphinxで使用されている（およびreStructuredText全般ではない）？ RSTを使用している人は、ある時点で両方のケースに遭遇する可能性が高いため、両方を取り上げます。

スフィンクス

クラス（:class:）などのさまざまなエンティティへのリンクに使用できるドメイン固有のディレクティブの他に、一般的な:ref:ディレクティブがあります。これは here で文書化されています。彼らはこの例を与えます：

    .. _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が提供する一般的なハイパーリンクメカニズムはSphinxで機能しますが、ドキュメントでは、Sphinxを使用する場合は使用しないことを推奨しています。

Refを使用することは、セクションへの標準のreStructuredTextリンク（Section title_など）よりも推奨されます。これは、セクション見出しが変更されたとき、および相互参照をサポートするすべてのBuilderで機能するためです。

RST、全般

RSTファイルをHTMLに変換するツールには、必ずしもcollectionという概念がありません。これは、たとえば、githubを使用してRSTファイルをHTMLに変換する場合、またはrst2htmlなどのコマンドラインツールを使用する場合です。残念ながら、目的の結果を得るために使用するさまざまな方法は、使用しているツールによって異なります。たとえば、rst2htmlを使用し、ファイルA.rstをファイルother.rstの「Section」というセクションにリンクし、最終的なHTMLをブラウザーで機能させる場合は、A.rstには以下が含まれます。

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

最終的なHTMLファイルにリンクする必要があり、セクションに指定されたidが何であるかを知る必要があります。 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``.

ここでも、セクションに与えられたidを知る必要があります。ただし、HTMLが作成されるのはRSTファイルにアクセスしたときのみであるため、RSTファイルにリンクします。 （この回答を書いている時点では、HTMLに直接アクセスすることは許可されていません。）

完全な例が利用可能です here 。

160
Louis

2016年の新しい、より良い答え！

autosection extension を使用すると、これを簡単に行うことができます。

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


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

それじゃあ、後でね...

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


A link-  :ref:`Internal Headline`

この拡張機能は組み込まれているため、必要なのはconf.py

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

注意する必要があるのは、ドキュメントコレクション全体で内部ヘッドラインを複製できないことです。 （価値がある。）

39
Adam Michael Wood

例：

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

ここで、Homebrewは、Installation.rstという名前の別のドキュメント内のセクションです。

これは 自動セクション機能 を使用するため、次のようにconfig.pyを編集する必要があります。

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