Sphinx: `:doc:`ロールに指定するパスには、拡張子を含めてはいけない

環境

• Sphinx 7.4.7

やりたいこと

reStructuredTextで、プロジェクト内のドキュメントを参照するリンクを生成したいです。

.
├── docs
│   ├── foo.rst
│   ├── bar.rst

foo.rstからbar.rstを参照するために、:doc:ロールを用いて以下のように記載しました。

foo.rst

:doc:`bar.rst`

しかし、ドキュメントを生成すると以下の警告メッセージが表示されて、リンクは生成されませんでした。なぜでしょうか？

WARNING: unknown document: 'bar.rst'

原因

:doc:ロールで指定したパスに、.rstという拡張子があるため"unknown document"というメッセージが表示されたようです。
拡張子を取り除けば、期待通りのリンクが生成されました。

foo.rst

:doc:`bar`

なお、toctreeディレクティブでは、拡張子がある場合でもない場合でもリンクは生成されます。

foo.rst

.. toctree::

   bar.rst
   bar

:doc:ロールでも同じような動きになって欲しいですね。

TODO https://github.com/sphinx-doc/sphinx にIssueを作成する

参考にしたサイト

• https://sphinx-users.jp/reverse-dict/writing/link.html ¹
• https://www.sphinx-doc.org/ja/master/usage/referencing.html#role-doc

1. サンプルコードには拡張子が付いていて正しくなかったので、Pull Requestを作成しました。 ↩