私はプロジェクトの文書化には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上のレポジトりのページにその部分が表示されなくなるのでやめたほうがよいでしょう。