今回は,READMEの書き方を初心者の方々に向けてお伝えしていこうと思います。本記事はpython実践講座シリーズの内容になります。その他の記事は,こちらの「Python入門講座/実践講座まとめ」をご覧ください。
読みたい場所へジャンプ!
READMEの概要
はじめてGitHubのリポジトリなるものを見たとき,「README」というファイルを見つけたのを覚えています。最初は何を表しているファイルなのか全く検討つきませんでしたが,よくよく見てみると「私が公開しているこのコード群の使い方」を示しているものだと気がつきました。言われてみればその通りで「READ ME(まずはじめに私を読め)」ですもんね。
例えば,pytorchのREADMEを覗いてみましょう。
下までスクロールしていくと分かりますが,READMEは画像なども用いて分かりやすく表現していくもののようです。実際に,記法はmarkdownがよく用いられますので,画像やgifの埋め込みも簡単にできます。
リードミーはいわば,アップしているリポジトリの説明書のようなものです。書き方には人それぞれ流派がありますが,ここでは簡単に記載しておくべき内容を確認しておきましょう。以下で一つ一つに注目していきます。
【盛り込むべき内容】
●リポジトリ(プロダクト)の名前:Name
●概要:Overview
●デモ:Demo
●使い方:Usage
●環境:Requirement
●インストール方法:Install
●注意事項:Note
●文責:Author
●ライセンス:License
リポジトリ(プロダクト)の名前:Name
(Example)
# Music Generator
This tool enables you to generate great musics, even if you are not a professional music player.
まず最初に,公開するレポジトリの名前を書きます。論文で言うところのタイトルにあたります。自分の公開したいプロダクトを簡潔に表す題名を付けてあげましょう。その下に,簡単にプロダクトの説明を書いておきましょう。詳しくは下の「Description」で書くことになるので,本当にシンプルでOKです。
概要:Description
(Example)
# Description
This tool is based on deep neural generative models. The basic model is "Music VAE" [Adam, ICML, 2019].
先ほどの説明で伝えられなかった細かい部分に関する情報を記載します。本当に細かい部分に関しては論文などに掲載すればOKなので,こちらも気持ちさらう程度でOKかと思います。
デモ:Demo
ここでは,実際にどのようにツールが動作するかを記述します。gifなどを用いてエレガントなREADMEを作るとツールの凄さがカサ増しされます。どのように動くかを視覚的に説明できるとGoodです。
使い方:Usage
(Example)
# Usage
## train
```
$ python train.py "./datasets"
```
Argument: Tha path to the datasets you want to use.
## test
```
$ python test.py
```
There is no arguments.
## generate
```
$ python generate.py "jazz"
```
Argument: Tha genre of the music you want to generate.you can chose from "JPOP" or "jazz" or "samba".
ここでは,ツールを動かすためにはどのようなコマンドを用いれば良いのかを記載します。上では「動いた結果」を示しましたが,こちらは「動くための命令」を書きます。ターミナル上で引数を与える場合は,その旨も記載しておきましょう。データセットの細かい形式指定などもしておくと親切だと思います。
環境:Requirement
(Example)
# Requirements
- Ubuntu 16.04
- Python 3.7.3
- conda 4.7.12
- pytorch 1.2.0
使用する環境を書いておきます。どこまで詳しく書くかは個人の自由です。ツールのベースとなるライブラリのバージョンなどは必ず書くようにしておきましょう。
インストール方法:Install
ローカルなどにインストールさせるプロダクトを作成した場合は,インストール方法も書いておきます。
注意事項:Note
その他,補足情報や備考などを書きます。
文責:Author
この文章を書いた責任者を記載しておきます。
ライセンス:License
ネットの海に公開するためには,しっかりとライセンスを定めておく必要があります。
まとめ
一旦大まかなまとめは終了です。自分のプロダクトが完成して,本格的なREADMEを書く段階になり次第,情報を拡充していくつもりです。