[解決済み] sphinxはルートドキュメント以下のディレクトリにないドキュメントにリンクすることができますか？

質問

私はSphinxを使って、非Pythonプロジェクトのドキュメントを作成しています。 私は ./doc フォルダを各サブモジュールに配布したいのですが、その中には submodule_name.rst ファイルが含まれています。 次に、これらのファイルをマスター階層に吸い上げて、デザイン全体の仕様を作成したいと思います。

すなわち

Project
  docs
    spec
      project_spec.rst
      conf.py
  modules
    module1
      docs
        module1.rst
      src
    module2
      docs
        module2.rst
      src

マスターにあるファイルをインクルードしようとしたところ project_spec.rst ドキュメントのtoctreeに、このようなファイルをインクルードしようとしました。

.. toctree::
   :numbered:
   :maxdepth: 2

   Module 1 <../../modules/module1/docs/module1>

しかし、このようなエラーメッセージが表示されます。

警告: toctree は存在しないドキュメント u'modules/module1/docs/module1' への参照を含んでいます。

を使用することはできないのでしょうか？ ../ をドキュメントパスで使うことはできないのでしょうか？

更新：conf.pyの場所を追加

更新しました。 下記のincludeトリック以外では、まだ（2019年）不可能です。前倒しされ続けているオープン イシューがあります。 https://github.com/sphinx-doc/sphinx/issues/701

どのように解決するのですか？

はい、できます!

シンボリックリンクの代わりに (Windows では動作しません)、スタブドキュメントを作成します。 .. include:: ディレクティブしかないスタブドキュメントを作成します。

私は、ソースツリーの一番上にある README ファイルにリンクしようとして、これに遭遇しました。 というファイルに以下のように記述しました。 readme_link.rst :

.. include:: ../README

次に index.rst のように、toctreeにしました。

Contents:

.. toctree::
   :maxdepth: 2

   readme_link
   other_stuff

そして、インデックスページにリリースノートへのリンクができました。

おかげさまで http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html 提案に感謝します。