初めてのREADME.md

初めてのreadm.md

githubでよく見かけるREADME.md。誰が、何のために、何を、どうやって書いているのか調べてみました。今回は、自スクール用に開発中のDjangoプロジェクトのREADME.mdを実際に試行錯誤しながら作成しましたので、その手順をまとめます。

READMEとは

プロジェクトの説明、ツールの使い方、インストール方法などを理解してもらうために記述するもの

リードミー(Readme)とは、ソフトウェアを配布する際の添付文書のひとつ。配布物の一般的な情報を記載したファイルである。多くの場合、そのソフトウェアをインストールし使用する前に読むべきものとされている。

出典:Wikipedia

いわゆる、取説みたいな感じですね。

以下、ハーバード大のcs50(capstone project)からの引用です。

  • In a README.md in your project’s main directory, include a writeup describing your project, and specifically your file MUST include all of the following: (README.mdはプロジェクトのメインディレクトリに設置し、以下の内容を記述すること:)
    • Under its own header within the README called Distinctiveness and Complexity: Why you believe your project satisfies the distinctiveness and complexity requirements, mentioned above.(README内に「独自性と複雑さ」というヘッダーを置き、なぜあなたのプロジェクトの独自性と複雑さの要件を満たしていると信じているかを述べる)
    • What’s contained in each file you created.(あなたが作成したそれぞれのファイルに何が含まれているか)
    • How to run your application.(アプリの動かし方)
    • Any other additional information the staff should know about your project.(その他、スタッフが知っておくべき追加情報)

ハーバード大 cs50 capstone で提出された実際のREADME.md例

参考にさせて頂いたブログ:わかりやすいREADME.mdを書く

こちらも大変参考になりました:READMEの書き方

READMEのプロフィール作成アプリも発見:GitHub Profile README Generator


フォルダ構成テキストを自動生成してコピペしたい

markdownでフォルダ構成を記述するのがちょっとめんどうだったので、一気に生成できる方法を検索してみました。

以下のコマンドを入力すると、あっという間にツリーが完成(嬉)!

tree -aF -L 3 -I .git cap_03/capstone

参考にしたサイト:[Linux] ディレクトリ構成図作るのに便利だよ tree コマンド

capstone  
├── .gitignore* -- Telling Git which folder/file to ignore   
├── README.md*  -- This file  
├── capstone/   -- Main project folder   
│   ├── asgi.py*  -- ASGI config for capstone project  
│   ├── settings.py*  -- Modified: BASE_DIR, INSTALLED_APPS, TEMPLATES, DATABASES, ANGUAGE_CODE, TIME_ZONE, STATICFILES_DIRS, and LOGIN_URL  
│   ├── urls.py*  -- Project path configuration   
├── img/  -- Screenshots of each page/function  
├── manage.py*  
├── requirements.txt*  -- List of libraries needed to run  
├── static/  -- Admin CSS settings  
│   └── base_site.css*  -- Customized Admin CSS  
├── students/  Django students App  
│   ├── admin.py*  -- Fully customized for teacher input    
│   ├── apps.py*  -- students app config  
│   ├── forms.py*  -- Form for students to add words to remember  
│   ├── migrations/  -- Automatically Created and manage database definitions by making migration  
│   ├── models.py*  -- Database models  
│   ├── static/  -- Images, favicon, and CSS  
│   │   ├── images/  -- Static images  
│   │   └── students/  -- favicon and CSS  
│   │       ├── favicon.ico*   
│   │       └── styles.css*  
│   ├── templates/  -- HTML file folder for students app  
│   │   └── students/  -- Name space for url.py to find each file  
│   │       ├── ajax.html*  -- "My Words" page for students  
│   │       ├── base.html*  -- Settings common to all templates  
│   │       ├── index.html*  -- Filtered lesson data  
│   │       ├── login.html*  -- Student login page  
│   │       ├── mychart.html*  -- Filtered lesson data with a chart  
│   │       ├── myword.html*  -- Students' personal word list  
│   │       └── register.html*  -- Student register page   
│   ├── urls.py*  -- Student app path configration  
│   └── views.py*  -- All functions are hundled here  
├── templates/  -- Admin HTML customization  
│   └── admin/  
│       └── base_site.html* 

今回は使用しませんでしたが、他にも、VSCの拡張機能が色々とあり、簡単に作成できるようです。

File Tree Generator


markdown書き方

markdownは、プレビューを並べて書くとよい

左側がmarkdown、右側がプレビューです。

Visual Studio Code で2画面にし(右上の一番端っこの四角をクリック)、ctrl + shift + v (windows) でプレビュー表示。

絵文字(下の方の赤い旗)は、windows + ピリオド で使用できます。

github上では、こんな風に表示されます。



markdownにコードを貼り付けたい

参考にさせて頂いたサイト:Qiita Markdown 書き方 まとめ

コードの挿入の基本は“`(バッククオート3つ)でコードをくくることです。
` はバッククオートです。クォーテーション ‘ ではありません。ご注意を。

Qiita Markdown 書き方 まとめ


markdownにスクショを「簡単に」貼り付けたい

これは本当に助かりました:Markdownでスクショ画像をペーストする(VS Code)

おまけ:emoji (windows) 使い方


今回のまとめ

README.mdを書くと、なんだか、本物のディベロパー感が出て嬉しかったです。

読みやすいREADMEが書ける日が来るまで、日々練習ですね。

プロの人たちが残して下さった膨大な数のtutorialsには、いつも助けられ、感謝の気持ちでいっぱいです。

おすすめ記事

コメントを残す

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