sphinxは、ルートドキュメントの下のディレクトリにないドキュメントにリンクできますか？

Question 1

私は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の場所を追加しました

更新：以下のインクルードトリックを除いて、これはまだ（2019）不可能です。前進し続ける未解決の問題があります：https：//github.com/sphinx-doc/sphinx/issues/701

Question 2

はい、できます！

シンボリックリンク（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に感謝します

Question 3

答えはノーのようです。toc-treeにリストされているドキュメントは、ソースディレクトリ、つまり、マスタードキュメントとconf.py（およびサブディレクトリ）を含むディレクトリ内に存在する必要があります。

sphinx-devメーリングリストから：

STScIでは、Sphinxで個々のプロジェクトのドキュメントを作成し、（toctreeを使用して）これらの他のプロジェクト固有のドキュメントを多数含む「マスタードキュメント」も作成します。これを行うには、マスタードキュメントのドキュメントソースディレクトリにプロジェクトのドキュメントソースディレクトリへのシンボリックリンクを作成します。これは、toctreeがドキュメントソースツリーの外部にファイルを含めたくないように見えるためです。

したがって、を使用してファイルをコピーするのではなくshutil、Project/docs/specディレクトリ内のすべてのモジュールにシンボリックリンクを追加してみてください。シンボリックリンクを作成する場合Project/modulesは、tocツリー内のこれらのファイルを単にmodules/module1/docs/module1etcとして参照します。

Question 4

conf.pyで、sys.pathとos.pathを使用してシステムへの相対パスを追加します

例えば：

import os
import sys

sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../../Directory1'))
sys.path.insert(0, os.path.abspath('../../Directory2'))

次に、同じディレクトリ内の最初のファイルを参照して、通常どおりindex.rstを使用します。したがって、ローカルのSphinxフォルダーのindex.rstにあります。

Contents:

.. toctree::
   :maxdepth: 4

   Package1 <package1.rst>
   Package2 <package2.rst>
   Package3 <package3.rst>

次に、package1.rstで、通常どおり相対パッケージを参照できるようになります。

Package1 package
=====================

Submodules
----------

Submodule1 module
----------------------------------

.. automodule:: file_within_directory_1
    :members:
    :undoc-members:
    :show-inheritance:

Submodule1 module
----------------------------------

.. automodule:: file_within_directory_2
    :members:
    :undoc-members:
    :show-inheritance:

Question 5

ルートにindex.rstファイルのみを含み、Project / docsに他のすべてのsphinxのものを含むようにsphinxを構成することもできます。

Windowsの場合、すべてのsphinxファイルとdir（index.rstを除く）をdocs /に移動し、以下を変更しました。

docs/make.bat：変化する

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  .

に

set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS%  -c . ..

docs/conf.py：追加

sys.path.insert(0, os.path.abspath('..'))

Question 6

外部のjupyterノートブックを含めたいという違いで、非常によく似た問題を解決しました。nbsphinxをインストールしましたが、動作させることができませんでした。 うまくいかなかったもの：

パスにルートを含めたいディレクトリがありました。

conf.py：

import os import sys sys.path.insert(...
.. include:: directiveファイルの使用はドキュメントに含まれていましたが、そのままです。

最後に問題を解決したのはパッケージnbsphinx-linkのインストールでした

Question 7

バックアップする相対リンクを使用することが本当に不可能な場合の1つの解決策は、ファイルを仕様の仕様フォルダーツリーにコピーする../ために使用できshutilますが、conf.pyどうしても必要な場合を除いて、複数のコピーを作成したくないということです。