他のReSTファイルをsphinxプロジェクトに正しく含めるにはどうすればよいですか？

Question

手書きのドキュメンテーション/ユーザーガイド（sphinxを使用してReStructuredTextで記述）が非常に大きくなったため、.rstファイルをサブディレクトリに整理し始めました。

index.rstには、各サブディレクトリのsubindex.rstを含めています。このサブディレクトリには、他のサブディレクトリ用の他の.rstファイルが含まれています。

index.rst：

.. include:: subdir1/subindex.rst
.. include:: subdir2/subindex.rst

subdir1/subindex.rst：

.. include:: file1.rst
.. include:: file2.rst

原則として、sphinxが解析しようとする.rst- filesを再帰的に探していることを除いて、これはうまく機能します。現在作業中のディレクトリを変更せずに。したがって、include:: file1.rst内のsubdir1を参照すると失敗します。

この問題を回避するには、サブディレクトリを無視するようにexclude_patternを設定します。これは正しくないようです。

サブディレクトリの.rst-ファイルを含める正しい方法は何ですか？

Answer 1

toctreeディレクティブ は、必要な処理を実行する必要があります。

.. toctree::
    :glob:

    subdir1/*
    subdir2/*

グロブ*は、subdirs内のファイルをアルファベット順にソートします。ソートを回避するために、グロビングなしで順序を指定できます。

.. toctree::
    :maxdepth: 2

    subdir1/file2
    subdir1/file1
    subdir2/file1
    subdir2/file2

個別のページではなく1つの大きなページが必要な場合は、 make singlehtml を呼び出すことができます。