106

非 Python プロジェクトの文書化に Sphinx を使用しています。そのモジュールを文書化するためのファイルを./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

4

8 に答える 8

127

はい、できます！

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

于 2013-06-20T14:58:10.937 に答える
13

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

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

STScI では、個々のプロジェクトのドキュメントを Sphinx で作成し、(toctree を使用して) これらの他のプロジェクト固有のドキュメントを多数含む「マスター ドキュメント」も作成します。これを行うには、マスター ドキュメントのドキュメント ソース ディレクトリにプロジェクトのドキュメント ソース ディレクトリへのシンボリック リンクを作成します。

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

于 2012-04-18T13:48:33.420 に答える
1

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

Windows の場合、すべてのスフィンクス ファイルとディレクトリ (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('..'))
于 2015-09-07T08:09:17.153 に答える
0

バックアップする相対リンクを使用することが本当に不可能な場合の 1 つの解決策は、ファイルをスペックのスペック フォルダー ツリーにコピーするために../使用できますが、絶対に必要でない限り、複数のコピーを作成したくありません。shutilconf.py

于 2012-04-18T12:46:23.730 に答える