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

Question

環境

環境は（ある程度 Sphinx が最新に近ければ）何にでも通じるのではないかと思いますが、とりあえず、２環境 (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 へのリンクを実現するつもりで、１つめは index2.rst そのものへのリンク、２つめは 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 内に加筆したリンクのうち、１つめは正しく実現でき、リンククリックによって index2.html にジャンプします。２つめは、リンクがそもそも形成されません。

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> という記述が誤りであるのは間違いないですが、目的を達するためにはどう書けばよいのかがわかりません。

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

Answer 1

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

...

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

...

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

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

Comments

[matsuand]

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

[ka_ei]

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

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

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

[ka_ei]

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

[matsuand]

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