web-dev-qa-db-ja.com

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

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

pythonpython-sphinx
77
mc_electron

はい、できます！

（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 の提案に感謝

90
Dan Menes

答えはノーだと思われます。toc-treeにリストされているドキュメントは、 ソースディレクトリ 、つまり マスタードキュメント および_conf.py_（およびサブディレクトリ）。

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

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

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

14
Chris

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を使用し、同じディレクトリ内の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:
8
A Kingscote

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

0
mc_electron

また、rootにindex.rstファイルのみ、Project/docsにある他のすべてのsphinxのものだけを持つようにsphinxを構成することもできます。

Windowsの場合、すべてのsphinxファイルとディレクトリ（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('..'))
0
mrtnlrsn