reST/Sphinx ページに、同じドキュメント セット内の別のページのサブヘッダーまたはアンカーへの相互参照を挿入するにはどうすればよいですか?
ベストアンサー1
「reST/Sphinx」という表現は質問の範囲を曖昧にします。これはreStructuredText全般に関する質問でしょうか?そしてスフィンクス、またはのみreStructuredTextについて使用される場合Sphinx (reStructuredText 全般ではありません) ですか? RST を使用する人は、いずれ両方のケースに遭遇する可能性が高いため、両方について説明します。
スフィンクス
クラス()のような様々なエンティティにリンクするために使用できるドメイン固有のディレクティブの他に、文書化された:class:
一般的なディレクティブがあります。:ref:
ここ彼らは次のような例を挙げています。
.. _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 を使用するときにこれを使用しないことを推奨しています。
セクションへの標準の reStructuredText リンク (_ など) よりも ref を使用することをお勧めします。
Section title
これは、ファイル間で機能し、セクションの見出しが変更された場合や、相互参照をサポートするすべてのビルダーで機能するためです。
RST 全般
RSTファイルをHTMLに変換するツールは、必ずしもコレクション。これは、たとえば、github を使用して RST ファイルを HTML に変換する場合や、 などのコマンドライン ツールを使用する場合に当てはまりますrst2html
。残念ながら、目的の結果を得るために使用するさまざまな方法は、使用しているツールによって異なります。たとえば、 を使用しrst2html
、 をA.rst
ファイルの「Section」という名前のセクションにリンクしother.rst
、最終的な 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 に直接アクセスすることは許可されていません。)
完全な例はこちらここ。