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

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

新規登録して質問してみよう
ただいま回答率
85.50%
Sphinx

Sphinxは、reStructuredText記法で記述されたテキストファイルをHTML/PDF/epubといった様々な形式へ変換するドキュメントツールです。Pythonの公式ドキュメントを始め、多くのプロジェクトがSphinxを用いて記述されています。

Q&A

解決済

1回答

5999閲覧

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

matsuand

総合スコア186

Sphinx

Sphinxは、reStructuredText記法で記述されたテキストファイルをHTML/PDF/epubといった様々な形式へ変換するドキュメントツールです。Pythonの公式ドキュメントを始め、多くのプロジェクトがSphinxを用いて記述されています。

0グッド

1クリップ

投稿2019/05/20 04:36

環境

環境は(ある程度 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 へのリンクのつもり(<=これが実現できないもの)。

sphinx

1... 2 3This is a :doc:`link test for index2 </index2>`. 4 5This is a :doc:`link test for index2#testid </index2.rst#testid>`. 6 7...

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

sphinx

1Test2 2================================ 3 4This is a test2 document. 5 6.. _testid: 7 8testid 9------- 10 11This 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> という記述が誤りであるのは間違いないですが、目的を達するためにはどう書けばよいのかがわかりません。

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

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

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

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

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

guest

回答1

0

ベストアンサー

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

sphinx

1... 2 3This is a :ref:`link test for index2#testid <testid>`. 4 5...

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

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

投稿2019/07/22 09:44

ka_ei

総合スコア207

バッドをするには、ログインかつ

こちらの条件を満たす必要があります。

matsuand

2019/07/26 12:03

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

2019/08/01 09:45

認識合っています。ラベル(リファレンスID)の一意性の担保はドキュメント管理者が行う必要があります。下記ページもご参照ください。 http://www.sphinx-doc.org/ja/stable/markup/inline.html#ref-role 「ラベルはユニークである必要があります。」という記載の通りです。
ka_ei

2019/08/01 09:48

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

2019/08/01 12:28

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

あなたの回答

tips

太字

斜体

打ち消し線

見出し

引用テキストの挿入

コードの挿入

リンクの挿入

リストの挿入

番号リストの挿入

表の挿入

水平線の挿入

プレビュー

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

ただいまの回答率
85.50%

質問をまとめることで
思考を整理して素早く解決

テンプレート機能で
簡単に質問をまとめる

質問する

関連した質問