質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

88.78%

Sphinxでの内部サイト参照リンク方法

解決済

回答 1

投稿

  • 評価
  • クリップ 1
  • VIEW 1,483

matsuand

score 155

環境

環境は(ある程度 Sphinx が最新に近ければ)何にでも通じるのではないかと思いますが、とりあえず、2環境 (1)Ubuntu 19.04、sphinx-build 1.8.5 (apt-get install python3-sphinx)、(2)Cygwin 2.11.2、sphinx-build 2.0.1 (python3) です。

概要

ごく単純に HTML ファイルにおける <a href="http://someurl/index.html#someid"> のようなこと("#someid" の部分相当)を Sphinx 文書(HTML変換)で行いたいです。これを実現するのに、以下のようなことを(そもそもどう書いたら良いのか不明であったため当てずっぽうで)書いてみましたが、実現はできません。

This is a :doc:`link test for some#someid </some.rst#someid>`

実現するにはどうしたらよいでしょうか?

詳細(再現方法)

sphinx-quickstart でサンプル文書を作成し、index.rst に以下を加えました。別文書(後述)index2.rst へのリンクを実現するつもりで、1つめは index2.rst そのものへのリンク、2つめは index2.rst#testid へのリンクのつもり(<=これが実現できないもの)。

...

This is a :doc:`link test for index2 </index2>`.

This is a :doc:`link test for index2#testid </index2.rst#testid>`.

...

以下、index2.rst を新規生成。中身はごくシンプル。

Test2
================================

This is a test2 document.

.. _testid:

testid
-------

This is testid section.

以上を準備して、サンプル文書を make html で HTML 文書化します。
メインの index.rst 内に加筆したリンクのうち、1つめは正しく実現でき、リンククリックによって index2.html にジャンプします。2つめは、リンクがそもそも形成されません。

Ubuntu 環境での処理メッセージ(エラー含む)は以下のとおりです。

Running Sphinx v1.8.5
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: [] 0 added, 1 changed, 0 removed
reading sources... [100%] index2

looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/matsuand/src/sphinx/test/index2.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [ 50%] index
writing output... [100%] index2

/home/matsuand/src/sphinx/test/index.rst:15: WARNING: unknown document: /index2.rst#testid
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in _build/html.

警告メッセージ WARNING: unknown document: /index2.rst#testid にあるように、index.rst での </index2.rst#testid> という記述が誤りであるのは間違いないですが、目的を達するためにはどう書けばよいのかがわかりません。

よろしくお願いいたします。

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 過去に投稿した質問と同じ内容の質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 1

checkベストアンサー

0

docではなくてrefを使って下記のようにすればできるはずです。

...

This is a :ref:`link test for index2#testid <testid>`.

...

この時、ドキュメント名は特に指定する必要はないです。
ただし、testidはドキュメント群の中で一意になっている必要があるので注意が必要です。

※一意になっていないと、makeしたときに「WARNING: malformed hyperlink target.」と怒られます

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2019/07/26 21:03

    ありがとうございます。その方法しかないのですね。これは Sphinx の改善点になるような気がします。
    何百、何千ページにもわたるような、たとえばAPIマニュアルのようなものを想定しますと、各ページに「関数書式(format)」とか「利用例(example)」とか「参照(reference)」などといった節が出現してくると思います。これに対して、Sphinx ユーザーは、リファレンスID(?)として、単に #format とか #example と命名することが出来ず、それぞれ #functionA-format、#functionB-format などのように、リファレンスIDを自己管理していかなければならないことを意味し、ユーザーにあまり「やさしくない」部分と感じます。
    理解が間違っていたり不足していたりしたら、ご指摘ください。

    キャンセル

  • 2019/08/01 18:45

    認識合っています。ラベル(リファレンスID)の一意性の担保はドキュメント管理者が行う必要があります。下記ページもご参照ください。

    http://www.sphinx-doc.org/ja/stable/markup/inline.html#ref-role

    「ラベルはユニークである必要があります。」という記載の通りです。

    キャンセル

  • 2019/08/01 18:48

    おっしゃる通り膨大なドキュメントを想定した場合、優しくない仕様ですね。
    一意性を担保するための台帳か何かを用意するか、ドキュメント名をラベルのプレフィックスにするルールでドキュメント間のラベル名競合を避けるといった運用の工夫が必要ですね。

    キャンセル

  • 2019/08/01 21:28

    ご丁寧にありがとうございます。

    キャンセル

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 88.78%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る