LoginSignup
3
5

More than 5 years have passed since last update.

READMEと同じ内容をドキュメントにも含める方法

Posted at

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

3
5
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
3
5