[解決済み] ソースディレクトリとビルドディレクトリを分離する」とはどういう意味ですか？

質問

初めてSphinxを使おうとしています。私は sphinx-quickstart が、最初に聞かれた質問が理解できません。

> Separate source and build directories (y/n) [n]: 

これはどういうことでしょうか？これらのディレクトリが分離されているかどうかで、どのような違いがあるのでしょうか？どちらを選べばいいのか、どうすればわかるのでしょうか？

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

簡単に言うと、オプション "ビルドからソースを分離する"。 の sphinx-quickstart ツールは、2つの可能なディレクトリ/ファイル構造のレイアウトを導きます。

1. はい」を選択すると、次のような画面が表示されます。 build ディレクトリと source ディレクトリを作成します。

   生成された .rst ファイルおよび conf.py が配置されます。 source ディレクトリを作成します（その後、任意の .rst ファイルもそこに置く必要があります）。SphinxがreStructuredTextのソースファイルから生成する、最終的なドキュメントファイル(例えばHTML)は build ディレクトリを作成します。

   C:.
   │   make.bat
   │   Makefile
   │
   ├───build
   └───source
       │   conf.py
       │   index.rst
       │
       ├───_static
       └───_templates
   
   

   を実行したときの抜粋です。 sphinx-quickstart ツールで "YES" を選択して、ソースとビルドを分離しています。

   Creating file C:\Your_Project\docs\source\conf.py.
   Creating file C:\Your_Project\docs\source\index.rst.
   Creating file C:\Your_Project\docs\Makefile.
   Creating file C:\Your_Project\docs\make.bat.
   
   Finished: An initial directory structure has been created.
   
   

2. No"を選択した場合（分離しない）。 source ディレクトリが作成されないので、そのディレクトリに置かれていたコンテンツが source ディレクトリに置かれます。 sphinx-quickstart .

   また、ビルドディレクトリも若干異なり、アンダースコアが付きます。 _build という名前になります。

   C:.
   │   conf.py
   │   index.rst
   │   make.bat
   │   Makefile
   │
   ├───_build
   ├───_static
   └───_templates
   
   

   を実行したときの抜粋です。 sphinx-quickstart ツールで "NO" を選択して、ソースとビルドを分離しています。

   Separate source and build directories (y/n) [n]: 
   
   Creating file C:\Your_Project\docs\conf.py.
   Creating file C:\Your_Project\docs\index.rst.
   Creating file C:\Your_Project\docs\Makefile.
   Creating file C:\Your_Project\docs\make.bat.
   
   Finished: An initial directory structure has been created.
   
   

どれを選べばいいのか、どうすればいいのか？

私が見た中で最も一般的な選択肢は、「分離」を選択することです。 sources から build . ファイルを分けておくことで、大きなプロジェクトでは間違いなく物事がより整理されます。唯一の欠点は、ディレクトリの数が増えることで、最初は混乱するかもしれませんが、分離を増やすことは長い目で見れば価値があることなのです。