Merge pull request #149 from katsutan/feature/readme

kazuma-t · web-flow · commit 89b6d27aa3eb · 2020-12-18T18:38:13.000+09:00
add Japanese tutorial
diff --git a/README.md b/README.md
@@ -4,6 +4,8 @@
 [![Build Status](https://travis-ci.com/WorksApplications/SudachiPy.svg?branch=develop)](https://travis-ci.com/WorksApplications/SudachiPy)
 [![](https://img.shields.io/github/license/WorksApplications/SudachiPy.svg)](https://github.com/WorksApplications/SudachiPy/blob/develop/LICENSE)
 
+[日本語](/docs/tutorial.md)
+
 SudachiPy is a Python version of [Sudachi](https://github.com/WorksApplications/Sudachi), a Japanese morphological analyzer.
 
 
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -1,32 +1,320 @@
-**（このドキュメントは古いです。いまはREADME.mdを参照ください。近日アップデート予定）**
+# 日本語形態素解析器 SudachiPy チュートリアル
+[![PyPi version](https://img.shields.io/pypi/v/sudachipy.svg)](https://pypi.python.org/pypi/sudachipy/)
+[![](https://img.shields.io/badge/python-3.5+-blue.svg)](https://www.python.org/downloads/release/python-350/)
+[![Build Status](https://travis-ci.com/WorksApplications/SudachiPy.svg?branch=develop)](https://travis-ci.com/WorksApplications/SudachiPy)
+[![](https://img.shields.io/github/license/WorksApplications/SudachiPy.svg)](https://github.com/WorksApplications/SudachiPy/blob/develop/LICENSE)
 
-# 日本語形態素解析器 SudachiPy（[Sudachi](https://github.com/WorksApplications/Sudachi/) Pythonクローン） チュートリアル
+SudachiPyは日本語形態素解析器[Sudachi](https://github.com/WorksApplications/Sudachi)のpython版です。
 
-pip をつかってインストールします。Python 3.5以上が必要です。 
 
+## とりあえず動かしたい場合
+
+```
+$ pip install sudachipy sudachidict_core
+
+$ echo "高輪ゲートウェイ駅" | sudachipy
+高輪ゲートウェイ駅	名詞,固有名詞,一般,*,*,*	高輪ゲートウェイ駅
+EOS
+
+$ echo "高輪ゲートウェイ駅" | sudachipy -m A
+高輪	名詞,固有名詞,地名,一般,*,*	高輪
+ゲートウェイ	名詞,普通名詞,一般,*,*,*	ゲートウェー
+駅	名詞,普通名詞,一般,*,*,*	駅
+EOS
+
+$ echo "空缶空罐空きカン" | sudachipy -a
+空缶	名詞,普通名詞,一般,*,*,*	空き缶	空缶	アキカン	0
+空罐	名詞,普通名詞,一般,*,*,*	空き缶	空罐	アキカン	0
+空きカン	名詞,普通名詞,一般,*,*,*	空き缶	空きカン	アキカン	0
+EOS
 ```
-$ pip install -e git+git://github.com/WorksApplications/SudachiPy@develop#egg=SudachiPy
+
+## 導入
+
+SudachiPyを使う場合は辞書が必要になります。
+※パッケージには辞書が含まれていません。
+
+### Step 1. SudachiPyのインストール
+
+```bash
+$ pip install sudachipy
+```
+
+### Step 2. 辞書のインストール
+
+辞書はPythonのパッケージとしてダウンロードできます。
+
+※辞書のダウンロードは時間がかかります (`core`辞書は約70MB ).
+
+```bash
+$ pip install sudachidict_core
 ```
 
-パッケージには辞書が含まれていません。Java版をビルドして target/system_*.dic を取得するか、[リリース一覧](https://github.com/WorksApplications/Sudachi/releases)から辞書を取得します。 
+また、他の辞書を選択することもできます。詳細は[このセッション](#辞書の種類)を参照してください。
+
 
+## 使用方法（CLI）
+CLIでは以下のように実行できます。
+
+```bash
+$ echo "外国人参政権" | sudachipy
+外国人参政権	名詞,普通名詞,一般,*,*,*	外国人参政権
+EOS
+$ echo "外国人参政権" | sudachipy -m A
+外国	名詞,普通名詞,一般,*,*,*	外国
+人	接尾辞,名詞的,一般,*,*,*	人
+参政	名詞,普通名詞,一般,*,*,*	参政
+権	接尾辞,名詞的,一般,*,*,*	権
+EOS
 ```
-$ wget https://github.com/WorksApplications/Sudachi/releases/download/v0.1.1/sudachi-0.1.1-dictionary-core.zip
-$ unzip sudachi-0.1.1-dictionary-core.zip
-$ cp system_core.dic `pip show sudachipy | grep Location | sed 's/^.*: //'`/resources/system.dic
+
+```bash
+$ sudachipy tokenize -h
+usage: sudachipy tokenize [-h] [-r file] [-m {A,B,C}] [-o file] [-a] [-d] [-v]
+                          [file [file ...]]
+
+Tokenize Text
+
+positional arguments:
+  file           text written in utf-8
+
+optional arguments:
+  -h, --help     show this help message and exit
+  -r file        the setting file in JSON format
+  -m {A,B,C}     the mode of splitting
+  -o file        the output file
+  -a             print all of the fields
+  -d             print the debug information
+  -v, --version  print sudachipy version
 ```
 
-コマンドラインツールの利用方法は[Java版](https://github.com/WorksApplications/Sudachi/blob/develop/docs/tutorial.md)とほぼ同じです。 
+### 出力形式
+タブ区切りで出力されます。
+デフォルトは以下の情報が含まれます。
+
+- 表層形
+- 品詞（コンマ区切り）
+- 正規化表記
+
+オプションで `-a` を指定すると以下の情報が追加されます。
+
+- 辞書形
+- 読み
+- 辞書ID
+  - `0` システム辞書
+  - `1` ユーザー辞書
+  - `-1\t(OOV)` 未知語（辞書に含まれない単語）
 
+```bash
+$ echo "外国人参政権" | sudachipy -a
+外国人参政権	名詞,普通名詞,一般,*,*,*	外国人参政権	外国人参政権	ガイコクジンサンセイケン	0
+EOS
 ```
-$ sudachipy
-きょうはいい天気ですね。
-きょう  名詞,普通名詞,副詞可能,*,*,*    今日
-は      助詞,係助詞,*,*,*,*     は
-いい    形容詞,非自立可能,*,*,形容詞,連体形-一般        良い
-天気    名詞,普通名詞,一般,*,*,*        天気
-です    助動詞,*,*,*,助動詞-デス,終止形-一般    です
-ね      助詞,終助詞,*,*,*,*     ね
-。      補助記号,句点,*,*,*,*   。
+
+```bash
+echo "阿quei" | sudachipy -a
+阿	名詞,普通名詞,一般,*,*,*	阿	阿		-1	(OOV)
+quei	名詞,普通名詞,一般,*,*,*	quei	quei		-1	(OOV)
 EOS
 ```
+
+## 使用方法(Python パッケージ)
+
+例 
+
+```python
+from sudachipy import tokenizer
+from sudachipy import dictionary
+
+tokenizer_obj = dictionary.Dictionary().create()
+```
+
+```python
+# 複数粒度分割
+
+mode = tokenizer.Tokenizer.SplitMode.C
+[m.surface() for m in tokenizer_obj.tokenize("国家公務員", mode)]
+# => ['国家公務員']
+
+mode = tokenizer.Tokenizer.SplitMode.B
+[m.surface() for m in tokenizer_obj.tokenize("国家公務員", mode)]
+# => ['国家', '公務員']
+
+mode = tokenizer.Tokenizer.SplitMode.A
+[m.surface() for m in tokenizer_obj.tokenize("国家公務員", mode)]
+# => ['国家', '公務', '員']
+```
+
+```python
+# 形態素情報
+
+m = tokenizer_obj.tokenize("食べ", mode)[0]
+
+m.surface() # => '食べ'
+m.dictionary_form() # => '食べる'
+m.reading_form() # => 'タベ'
+m.part_of_speech() # => ['動詞', '一般', '*', '*', '下一段-バ行', '連用形-一般']
+```
+
+```python
+# 正規化
+
+tokenizer_obj.tokenize("附属", mode)[0].normalized_form()
+# => '付属'
+tokenizer_obj.tokenize("SUMMER", mode)[0].normalized_form()
+# => 'サマー'
+tokenizer_obj.tokenize("シュミレーション", mode)[0].normalized_form()
+# => 'シミュレーション'
+```
+
+(これは `20200330` `core` 辞書による出力例です。 辞書のバージョンによって変わる可能性があります。)
+
+## 辞書の種類
+Sudachi辞書は`small`と`core`と`full`の3種類があります。 詳細は[WorksApplications/SudachiDict](https://github.com/WorksApplications/SudachiDict)を参照してください。
+
+SudachiPyはデフォルトでは`sudachidict_core`に設定されています。辞書設定の変更は`link -t`コマンドによって行えます。
+
+
+```bash
+$ pip install sudachidict_small
+$ sudachipy link -t small
+```
+
+```bash
+$ pip install sudachidict_full
+$ sudachipy link -t full
+```
+
+`link -u`によってリンクを削除するとデフォルトの`sudachidict_core`を使用します。
+
+```bash
+$ sudachipy link -u
+```
+
+`sudachidict_small`, `sudachidict_core`, `sudachidict_full`はPythonのパッケージとしてインストールされます。 SudachiPyは辞書を使用するとき`sudachidict` パッケージを参照します。 `link` によって`sudachidict_*`を`sudachidict`として参照するための *symbolic link* が作られます。
+
+* [SudachiDict-small · PyPI](https://pypi.org/project/SudachiDict-small/)
+* [SudachiDict-core · PyPI](https://pypi.org/project/SudachiDict-core/)
+* [SudachiDict-full · PyPI](https://pypi.org/project/SudachiDict-full/)
+
+辞書ファイルはパッケージ自体には含まれていませんが、上記のインストール時にダウンロードする処理が埋め込まれています。
+
+### 辞書の設定ファイル
+
+また、`sudachi.json`で辞書ファイルを切り替えることができます。
+
+
+```
+{
+    "systemDict" : "relative/path/to/system.dic",
+    ...
+}
+```
+
+デフォルトは[sudachipy/resources/sudachi.json](https://github.com/WorksApplications/SudachiPy/blob/develop/sudachipy/resources/sudachi.json)を参照します。 `sudachi.json`を新たに用意する場合は `-r`で指定してください.
+
+```bash
+$ sudachipy -r path/to/sudachi.json
+``` 
+
+## ユーザー辞書
+ユーザー辞書`user.dic`を使用する場合は、[sudachi.json](https://github.com/WorksApplications/SudachiPy/blob/develop/sudachipy/resources/sudachi.json)を好きな場所に配置し、`sudachi.json`から`user.dic`への相対パスをuserDictの値に追加してください。
+
+```js
+{
+    "userDict" : ["relative/path/to/user.dic"],
+    ...
+}
+```
+
+そして、その `sudachi.json`を`-r`で指定します。
+
+```bash
+$ sudachipy -r path/to/sudachi.json
+``` 
+
+サブコマンド`ubuild`によってユーザー辞書を作成できます。
+
+**WARNING: v0.3.\* ubuildはバグを含んでいます**
+
+```bash
+$ sudachipy ubuild -h
+usage: sudachipy ubuild [-h] [-d string] [-o file] [-s file] file [file ...]
+
+Build User Dictionary
+
+positional arguments:
+  file        source files with CSV format (one or more)
+
+optional arguments:
+  -h, --help  show this help message and exit
+  -d string   description comment to be embedded on dictionary
+  -o file     output file (default: user.dic)
+  -s file     system dictionary (default: linked system_dic, see link -h)
+```
+
+辞書ファイル形式については[user_dict.md](https://github.com/WorksApplications/Sudachi/blob/develop/docs/user_dict.md)を参照してください。 
+
+
+## システム辞書のカスタマイズ
+
+```bash
+$ sudachipy build -h
+usage: sudachipy build [-h] [-o file] [-d string] -m file file [file ...]
+
+Build Sudachi Dictionary
+
+positional arguments:
+  file        source files with CSV format (one of more)
+
+optional arguments:
+  -h, --help  show this help message and exit
+  -o file     output file (default: system.dic)
+  -d string   description comment to be embedded on dictionary
+
+required named arguments:
+  -m file     connection matrix file with MeCab's matrix.def format
+```
+
+カスタマイズしたシステム辞書`system.dic`を使用する場合は、[sudachi.json](https://github.com/WorksApplications/SudachiPy/blob/develop/sudachipy/resources/sudachi.json)を好きな場所に配置し、`sudachi.json`から`system.dic`への相対パスでsystemDictの値を上書きしてください。
+
+```
+{
+    "systemDict" : "relative/path/to/system.dic",
+    ...
+}
+```
+
+そして、その `sudachi.json`を`-r`で指定します。
+
+```bash
+$ sudachipy -r path/to/sudachi.json
+``` 
+
+## 開発者向け
+### Cython Build
+
+```sh
+$ python setup.py build_ext --inplace
+```
+
+### Code Format
+
+`scripts/format.sh`を実行して、コードが正しいフォーマットかを確認してください。
+
+`flake8` `flake8-import-order` `flake8-buitins`が必要です。 (`requirements.txt`参照).
+
+### Test
+
+`scripts/test.sh`を実行してテストしてください。
+
+
+## Contact
+
+SudachiとSudachiPyは[WAP Tokushima Laboratory of AI and NLP](http://nlp.worksap.co.jp/)によって開発されています.
+
+開発者やユーザーの方々が質問したり議論するためのSlackワークスペースを用意しています。
+
+- https://sudachi-dev.slack.com/ ([こちら](https://join.slack.com/t/sudachi-dev/shared_invite/enQtMzg2NTI2NjYxNTUyLTMyYmNkZWQ0Y2E5NmQxMTI3ZGM3NDU0NzU4NGE1Y2UwYTVmNTViYjJmNDI0MWZiYTg4ODNmMzgxYTQ3ZmI2OWU)から招待を受けてください)
+
+
