READMEに説明を記載

Author: tokibito

README.md

@@ -1,18 +1,65 @@
-# Note application
+# ノートアプリケーション
 
 [![Build Status](https://travis-ci.org/tokibito/note-app-django-vue-javascript.svg?branch=master)](https://travis-ci.org/tokibito/note-app-django-vue-javascript)
 
 ![ノート](note-app.png "ノート")
 
-## make python virtualenv and activate
+## これは何ですか?
 
-```
-python3.6 -m venv venv
-source venv/bin/activate
-```
+テキストを編集、保存できるシンプルなウェブアプリケーションです。
 
-## install python modules
+バックエンドとなるAPIサーバーにはDjangoフレームワーク(Python)、フロントエンドにはVue.js(JavaScript)を使っています。
 
-```
-pip install -r requirements.txt
-```
+DjangoフレームワークとJavaScriptでアプリケーションを作るサンプルコードとして作成しました。
+
+以下の要素を含んでいます:
+
+* バックエンド
+   * Python3
+   * venv
+   * Djangoフレームワーク
+      * Django REST Framework
+* フロントエンド
+   * Babel
+   * webpack
+   * Vue.js
+   * Bootstrap
+   * Font Awesome
+   * mocha
+   * power-assert
+
+## 構成
+
+* `note_server`
+   * バックエンド(Pythonで動作するAPIサーバー)
+* `note_client`
+   * フロントエンド(webpackでビルドし、Djangoフレームワークのstaticfilesモジュールから配信される)
+   * CSS(Sass)も含む
+
+## 動かしてみる
+
+1. `note_client` をビルドする
+2. `note_server` を起動してブラウザでアクセスする
+
+## 設計について
+
+アーキテクチャとモジュール構成に関して考えた点など:
+
+* シングルページアプリケーション(SPA)にはせず、DjangoのサーバーサイドレンダリングとVue.jsを組み合わせて使う
+   * ビルドしたファイルの配信は、Djangoフレームワークのstaticfilesに任せる
+* Vuexはなるべく使わない
+   * 依存をなるべく減らす気持ち
+   * Vuexは学習コストもメンテコストも高いので、使わないで済むうちは使わない
+      * 複雑になったら使ったほうが楽できるとは思います
+* vue-cliを使っていない
+   * ごちゃっと余計なものが入るのを避ける
+   * 使うツールスタックを合わせられるなら使ってもよいかな
+* Vueへの依存をなるべく広げない
+   * Vueに依存しないほうがテストコードを書きやすいから
+   * Vueインスタンスをエントリポイント(index.js)外のJavaScriptコードに渡さない
+      * エントリポイントではVueに依存しないコントローラクラスのインスタンスを生成し、データはコントローラに持たせる
+         * 規模が大きくなったらストアを用意するかも
+   * コンポーネントから外へVueインスタンスを渡さない
+* django-webpack-loaderを使っていない
+   * なるべく依存を増やさない
+   * 必要になったら入れよう

note_client/README.md

@@ -1,30 +1,30 @@
-# Client Application
+# クライアントアプリケーション
 
-## install node packages
+## Node.JSのパッケージをインストールする
 
 ```
 npm i
 ```
 
-## bulid
+## アプリケーションのビルド
 
 ```
 npm run webpack
 ```
 
-## watch build
+## ファイルの変更を検知してビルド
 
 ```
 npm run webpack -- -w
 ```
 
-## clean
+## ビルドされたファイル群の削除
 
 ```
 npm run clean
 ```
 
-## run test
+## テストコードの実行
 
 ```
 npm t

note_server/README.md

@@ -1,18 +1,41 @@
-# Note API Server
+# APIサーバー
 
-## migrate
+Djangoフレームワーク、Django REST Frameworkを使っています。
+
+## virtualenvの作成、有効化
+
+```
+python3.6 -m venv venv
+source venv/bin/activate
+```
+
+## Pythonモジュールのインストール
+
+virtualenvを有効にした状態で、pipコマンドでインストールします。
+
+```
+pip install -r requirements.txt
+```
+
+## データベースファイルの作成とマイグレーション
+
+データベースはデフォルトのSQLite3を使います。 `migrate` コマンドでデータベースファイルが作成され、マイグレーションも実行されます。
 
 ```
 ./manage.py migrate
 ```
 
-## create user
+## ユーザーの作成
+
+このアプリケーションはDjangoの標準機能を使用したユーザー認証があります。管理者となるユーザーはcreatesuperuserコマンドで作成します。
 
 ```
 ./manage.py createsuperuser
 ```
 
-## runserver
+## 開発用サーバーの起動
+
+開発用サーバーは `runserver` コマンドで起動します。
 
 ```
 ./manage.py runserver