web-dev-qa-db-ja.com

任意のラベルを作成せずに、sphinx restructuredtextの見出しへの内部リンクを作成するにはどうすればよいですか？

多くの見出しと小見出しのあるドキュメントがあります。テキストのさらに奥に、見出しの1つにリンクして戻したいと思います。 :ref:ラベルの冗長性なしでこれを行うにはどうすればよいですか？内容はヘッダーをうまく拾っているようです。私はこのようなものを望んでいました：`#polled-data-retrieval`_。

python-sphinxrestructuredtext
24
caduceus

reStructuredTextは 暗黙のハイパーリンクターゲット をサポートします。 reStructuredTextクイックリファレンス から：

セクションのタイトル、脚注、および引用は、ハイパーリンクターゲットを自動的に生成します（タイトルテキストまたは脚注/引用ラベルがハイパーリンク名として使用されます）。

したがって、次のテキスト（reStructuredTextクイックリファレンス、スペルミスなどから削除）：

Titles are targets, too
=======================
Implict references, like `Titles are targets, too`_.

次のようなHTMLを生成します。

<strong><a name="title">Titles are targets, too</a></strong>

<p>Implict references, like <a href="#title">Titles are targets, too</a>.</p>
30
Chris

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',
]

注意しなければならない唯一のことは、ドキュメントコレクション全体で内部見出しを複製できないことです。 （価値がある。）

19
Adam Michael Wood

クリスによる答えへの小さな追加：

リンクにその見出しの正確な名前を使用せずに見出しにリンクする場合は、次のように行うことができます。

Titles are targets, too
=======================

See `here <#titles-are-targets-too>`_

これは次のようにレンダリングされます：

<h1 id="titles-are-targets-too">Titles are targets, too</h1>

<p>See <a href="#titles-are-targets-too">here</a></p>
15
Baleb

見出しのテキストを使用することは良い選択ではありません。見出しが変更されたり、修正されたりする場合があります。変更後にリンクが切断された人の数と場所を簡単に把握できるようになりました。

Refを使用することは、セクションへの標準のreStructuredTextリンク（`Section title`_など）よりも推奨されます。これは、ファイル間で機能し、セクションの見出しが変更されると、正しくない場合は警告が表示され、相互参照をサポートするすべてのビルダーで機能するためです。
出典： https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref

Adam Michael Wood によって提案された sphinx.ext.autosectionlabel extension の使用は、 Chris によって提案された暗黙的に定義されたアンカーを使用するよりも少なくともより構造化されたアプローチです=。

参照およびシンボリックターゲット名との明示的なリンクを使用する必要があります（LaTeXが古くから使用しているように）。

  1. .. _refname:を使用してターゲットを作成します。
  2. :ref:`refname`を使用してターゲットを参照します。

ターゲットの後に見出しが続く場合、この見出しはリンクテキストとして使用されます。

2
Paebbels