アカデミック

【超初心者向け】はじめてのREADME.md

コード書いたはいいけど人に見せられる代物じゃない…
他人に自作コードを使ってもらうにはどうすればいいんだろう?

 

今回は,READMEの書き方を初心者の方々に向けてお伝えしていこうと思います。本記事はpython実践講座シリーズの内容になります。その他の記事は,こちらの「Python入門講座/実践講座まとめ」をご覧ください。

【超初心者向け】python入門講座/実践講座まとめ目次入門講座 1.実行環境 2.文字の出力 3.データ型 4.変数 5.更新と変換 6.比較演算子 7.論理演算子 8.条件分岐 9.リスト...
コーディングに関して未熟な部分がたくさんあると思いますので,もし何かお気づきの方は教えていただけると幸いです。また,誤りについてもご指摘していただけると非常に助かります。

READMEの概要

はじめてGitHubのリポジトリなるものを見たとき,「README」というファイルを見つけたのを覚えています。最初は何を表しているファイルなのか全く検討つきませんでしたが,よくよく見てみると「私が公開しているこのコード群の使い方」を示しているものだと気がつきました。言われてみればその通りで「READ ME(まずはじめに私を読め)」ですもんね。

例えば,pytorchのREADMEを覗いてみましょう。

PytorchのREADME

下までスクロールしていくと分かりますが,READMEは画像なども用いて分かりやすく表現していくもののようです。実際に,記法はmarkdownがよく用いられますので,画像やgifの埋め込みも簡単にできます。

リードミーはいわば,アップしているリポジトリの説明書のようなものです。書き方には人それぞれ流派がありますが,ここでは簡単に記載しておくべき内容を確認しておきましょう。以下で一つ一つに注目していきます。

【盛り込むべき内容】
●リポジトリ(プロダクト)の名前:Name
●概要:Overview
●デモ:Demo
●使い方:Usage
●環境:Requirement
●インストール方法:Install
●注意事項:Note
●文責:Author
●ライセンス:License

基本的にREADMEはマークダウン(.md)で書くことが多いです。今回もマークダウンで書いていきます。

 

リポジトリ(プロダクト)の名前: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を書く段階になり次第,情報を拡充していくつもりです。

COMMENT

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です