私はプロジェクトの文書化にはSphinxを利用していて、Sphinxのソースはそのプロジェクト内のdoc/source下に置いていてます。また、プロジェクトのREADMEもRSTで記述しています。例えば下図のような感じです。
project/
|
+--README.rst
|
+--doc/
: |
+--source/
| |
: +--overview.rst
|
:
GitHubのリポジトリのフロントページには、README.rstの内容が表示されるので、README.rstにはそのプロジェクトの概要を記述すると思いますが、同じような内容を、そのプロジェクトのドキュメント内にも含めたい場合があります。上の例では、ドキュメントのソースディレクトリ内のoverview.rst内に、README.rstとほぼ同じ内容を記述したい場合です。
同じ内容をoverview.rstにも記述すればよいのですが、修正するときに両方のファイルを更新しなければならず、どちらかを更新し忘れたりする恐れもあり、少し面倒です。できれば一カ所だけを更新したいものです。
解決策として、includeディレクティブを使用することで、overview.rsttに、README.rstから内容をoverview.rstに生成することが可能です。上の例では、次のようにoverview.rstに記述しビルドすると、README.rstの5行目から124行目までと同一の内容が、overview.rstのビルド結果にも生成されます。
.. include:: ../../README.rst
:start-line: 4
:end-line: 125
overview.rstに反映したい内容は、README.rst全体ではなく、一部だけだったりするので、この範囲を指定するオプションがはありがたいです。includeディレクティブにはこれ以外にもオプションがあるので、他にも便利なオプションがあるかもしれません。
ただし、GitHub上でoverview.rstを直接開けると、README.rstの内容は表示されません。セキュリティ上includeディレクティブは対応していないらしいです。反ですので、逆にREADME.rstにoverview.rstの内容をincludeするとGitHub上のレポジトりのページにその部分が表示されなくなるのでやめたほうがよいでしょう。