diff options
41 files changed, 3342 insertions, 0 deletions
diff --git a/docs/ja/cli.md b/docs/ja/cli.md new file mode 100644 index 0000000000..3cc58e1f05 --- /dev/null +++ b/docs/ja/cli.md @@ -0,0 +1,227 @@ +# QMK CLI + +<!--- + original document: d598f01cb:cli.md + git diff d598f01cb HEAD cli.md | cat +--> + +このページは QMK CLI のセットアップと使用方法について説明します。 + +# 概要 + +QMK CLI を使用すると QMK キーボードの構築と作業が簡単になります。QMK ファームウェアの取得とコンパイル、キーマップの作成などのようなタスクを簡素化し合理化するためのコマンドを多く提供します。 + +* [グローバル CLI](#global-cli) +* [ローカル CLI](#local-cli) +* [CLI コマンド](#cli-commands) + +# 必要事項 + +CLI は Python 3.5 以上を必要とします。我々は必要事項の数を少なくしようとしていますが、[`requirements.txt`](https://github.com/qmk/qmk_firmware/blob/master/requirements.txt) にリストされているパッケージもインストールする必要があります。 + +# グローバル CLI :id=global-cli + +QMK は、QMK ビルド環境のセットアップ、QMK の操作、および `qmk_firmware` の複数のコピーの操作を容易にできるインストール可能な CLI を提供します。これを定期的にインストールおよび更新することをお勧めします。 + +## Homebrew を使ったインストール (macOS、いくつかの Linux) + +[Homebrew](https://brew.sh) をインストールしている場合は、タップして QMK をインストールすることができます: + +``` +brew tap qmk/qmk +brew install qmk +export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します +qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします +``` + +## easy_install あるいは pip を使ってインストール + +上のリストにあなたのシステムがない場合は、QMK を手動でインストールすることができます。最初に、python 3.5 (以降)をインストールしていて、pip をインストールしていることを確認してください。次に以下のコマンドを使って QMK をインストールします: + +``` +pip3 install qmk +export QMK_HOME='~/qmk_firmware' # オプション、`qmk_firmware` の場所を設定します +qmk setup # これは `qmk/qmk_firmware` をクローンし、オプションでビルド環境をセットアップします +``` + +## 他のオペレーティングシステムのためのパッケージ + +より多くのオペレーティングシステム用に `qmk` パッケージを作成および保守する人を探しています。OS 用のパッケージを作成する場合は、以下のガイドラインに従ってください: + +* これらのガイドラインと矛盾する場合は、OS のベストプラクティスに従ってください + * 逸脱する場合は、理由をコメントに文章化してください。 +* virtualenv を使ってインストールしてください +* 環境変数 `QMK_HOME` を設定して、ファームウェアソースを `~/qmk_firmware` 以外のどこかにチェックアウトするようにユーザに指示してください。 + +# ローカル CLI :id=local-cli + +グローバル CLI を使いたくない場合は、`qmk_firmware` に付属のローカル CLI があります。`qmk_firmware/bin/qmk` で見つけることができます。任意のディレクトリから `qmk` コマンドを実行でき、常に `qmk_firmware` のコピー上で動作します。 + +**例**: + +``` +$ ~/qmk_firmware/bin/qmk hello +Ψ Hello, World! +``` + +## ローカル CLI の制限 + +グローバル CLI と比較して、ローカル CLI には幾つかの制限があります: + +* ローカル CLI は `qmk setup` あるいは `qmk clone` をサポートしません。 +* 複数のリポジトリがクローンされている場合でも、ローカル CLI は常に `qmk_firmware` ツリー上で動作します。 +* ローカル CLI は virtualenv で動作しません。そのため依存関係が競合する可能性があります + +# CLI コマンド :id=cli-commands + +## `qmk cformat` + +このコマンドは clang-format を使って C コードを整形します。引数無しで実行して全てのコアコードを整形するか、コマンドラインでファイル名を渡して特定のファイルに対して実行します。 + +**使用法**: + +``` +qmk cformat [file1] [file2] [...] [fileN] +``` + +## `qmk compile` + +このコマンドにより、任意のディレクトリからファームウェアをコンパイルすることができます。<https://config.qmk.fm> からエクスポートした JSON をコンパイルするか、リポジトリ内でキーマップをコンパイルすることができます。 + +**Configurator Exports での使い方**: + +``` +qmk compile <configuratorExport.json> +``` + +**キーマップでの使い方**: + +``` +qmk compile -kb <keyboard_name> -km <keymap_name> +``` + +## `qmk flash` + +このコマンドは `qmk compile` に似ていますが、ブートローダを対象にすることもできます。ブートローダはオプションで、デフォルトでは `:flash` に設定されています。 +違うブートローダを指定するには、`-bl <bootloader>` を使ってください。利用可能なブートローダの詳細については、<https://docs.qmk.fm/#/ja/flashing> +を見てください。 + +**Configurator Exports での使い方**: + +``` +qmk flash <configuratorExport.json> -bl <bootloader> +``` + +**キーマップでの使い方**: + +``` +qmk flash -kb <keyboard_name> -km <keymap_name> -bl <bootloader> +``` + +**ブートローダのリスト** + +``` +qmk flash -b +``` + +## `qmk config` + +このコマンドにより QMK の挙動を設定することができます。完全な `qmk config` のドキュメントについては、[CLI 設定](ja/cli_configuration.md)を見てください。 + +**使用法**: + +``` +qmk config [-ro] [config_token1] [config_token2] [...] [config_tokenN] +``` + +## `qmk docs` + +このコマンドは、ドキュメントを参照または改善するために使うことができるローカル HTTP サーバを起動します。デフォルトのポートは 8936 です。 + +**使用法**: + +``` +qmk docs [-p PORT] +``` + +## `qmk doctor` + +このコマンドは環境を調査し、潜在的なビルドあるいは書き込みの問題について警告します。 + +**使用法**: + +``` +qmk doctor +``` + +## `qmk json-keymap` + +QMK Configurator からエクスポートしたものから keymap.c を生成します。 + +**使用法**: + +``` +qmk json-keymap [-o OUTPUT] filename +``` + +## `qmk kle2json` + +このコマンドにより、生の KLE データから QMK Configurator の JSON へ変換することができます。絶対パスあるいは現在のディレクトリ内のファイル名のいずれかを受け取ります。デフォルトでは、`info.json` が既に存在している場合は上書きしません。上書きするには、`-f` あるいは `--force` フラグを使ってください。 + +**使用法**: + +``` +qmk kle2json [-f] <filename> +``` + +**例**: + +``` +$ qmk kle2json kle.txt +☒ File info.json already exists, use -f or --force to overwrite. +``` + +``` +$ qmk kle2json -f kle.txt -f +Ψ Wrote out to info.json +``` + +## `qmk list-keyboards` + +このコマンドは現在 `qmk_firmware` で定義されている全てのキーボードをリスト化します。 + +**使用法**: + +``` +qmk list-keyboards +``` + +## `qmk new-keymap` + +このコマンドは、キーボードの既存のデフォルトのキーマップに基づいて新しいキーマップを作成します。 + +**使用法**: + +``` +qmk new-keymap [-kb KEYBOARD] [-km KEYMAP] +``` + +## `qmk pyformat` + +このコマンドは `qmk_firmware` 内の python コードを整形します。 + +**使用法**: + +``` +qmk pyformat +``` + +## `qmk pytest` + +このコマンドは python のテストスィートを実行します。python コードに変更を加えた場合、これの実行が成功することを確認する必要があります。 + +**使用法**: + +``` +qmk pytest +``` diff --git a/docs/ja/cli_configuration.md b/docs/ja/cli_configuration.md new file mode 100644 index 0000000000..ce9746479c --- /dev/null +++ b/docs/ja/cli_configuration.md @@ -0,0 +1,126 @@ +# QMK CLI 設定 + +<!--- + original document: d598f01cb:cli_configuration.md + git diff d598f01cb HEAD cli_configuration.md | cat +--> + +このドキュメントは `qmk config` がどのように動作するかを説明します。 + +# はじめに + +QMK CLI の設定はキーバリューシステムです。各キーはピリオドで区切られたサブコマンドと引数名で構成されます。これにより、設定キーと設定された引数の間で簡単かつ直接的な変換が可能になります。 + +## 簡単な例 + +例として、`qmk compile --keyboard clueboard/66/rev4 --keymap default` コマンドを見てみましょう。 + +設定から読み取ることができる2つのコマンドライン引数があります: + +* `compile.keyboard` +* `compile.keymap` + +これらを設定してみましょう: + +``` +$ qmk config compile.keyboard=clueboard/66/rev4 compile.keymap=default +compile.keyboard: None -> clueboard/66/rev4 +compile.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +これで、毎回キーボードとキーマップを設定することなく、`qmk compile` を実行することができます。 + +## ユーザデフォルトの設定 + +複数のコマンド間で設定を共有したい場合があります。例えば、いくつかのコマンドは引数 `--keyboard` を受け取ります。全てのコマンドでこの値を設定する代わりに、その引数を受け取る全てのコマンドで使われるユーザ値を設定することができます。 + +例: + +``` +$ qmk config user.keyboard=clueboard/66/rev4 user.keymap=default +user.keyboard: None -> clueboard/66/rev4 +user.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# CLI ドキュメント (`qmk config`) + +`qmk config` コマンドは基礎となる設定とやり取りするために使われます。引数無しで実行すると、現在の設定を表示します。引数が指定された場合、それらは設定トークンと見なされます。設定トークンは以下の形式の空白を含まない文字列です: + + <subcommand|general|default>[.<key>][=<value>] + +## 設定値の設定 + +設定キーに等号 (=) を入れることで、設定値を設定することができます。キーは常に完全な `<section>.<key>` 形式である必要があります。 + +例: + +``` +$ qmk config default.keymap=default +default.keymap: None -> default +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## 設定値の読み込み + +設定全体、単一のキー、あるいはセクション全体の設定値を読み取ることができます。1つ以上の値を表示するために複数のキーを指定することができます。 + +### 全体の構成例 + + qmk config + +### セクション全体の例 + + qmk config compile + +### 単一キーの例 + + qmk config compile.keyboard + +### 複数キーの例 + + qmk config user compile.keyboard compile.keymap + +## 設定値の削除 + +設定値を特別な文字列 `None` に設定することで、設定値を削除することができます。 + +例: + +``` +$ qmk config default.keymap=None +default.keymap: default -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +## 複数の操作 + +複数の読み込みおよび書き込み操作を1つのコマンドに組み合わせることができます。それらは順番に実行および表示されます: + +``` +$ qmk config compile default.keymap=default compile.keymap=None +compile.keymap=skully +compile.keyboard=clueboard/66_hotswap/gen1 +default.keymap: None -> default +compile.keymap: skully -> None +Ψ Wrote configuration to '/Users/example/Library/Application Support/qmk/qmk.ini' +``` + +# ユーザ設定オプション + +| キー | デフォルト値 | 説明 | +|-----|---------------|-------------| +| user.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| user.keymap | None | キーマップ名 (例: `default`) | +| user.name | None | ユーザの github のユーザ名。 | + +# 全ての設定オプション + +| キー | デフォルト値 | 説明 | +|-----|---------------|-------------| +| compile.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| compile.keymap | None | キーマップ名 (例: `default`) | +| hello.name | None | 実行時の挨拶の名前 | +| new_keyboard.keyboard | None | キーボードのパス (例: `clueboard/66/rev4`) | +| new_keyboard.keymap | None | キーマップ名 (例: `default`) | diff --git a/docs/ja/contributing.md b/docs/ja/contributing.md new file mode 100644 index 0000000000..d1b28b1f58 --- /dev/null +++ b/docs/ja/contributing.md @@ -0,0 +1,173 @@ +# 貢献方法 + +<!--- + original document: d598f01cb:contributing.md + git diff d598f01cb HEAD contributing.md | cat +--> + +👍🎉 まず、これを読み貢献する時間を作ってくれてありがとうございます！🎉👍 + +サードパーティの貢献は、QMK の成長と改善に役立ちます。プルリクエストと貢献プロセスを貢献者とメンテナの両方にとって便利で簡単なものにしたいです。この目的のために、大きな変更をせずにプルリクエストが受け入れられるように貢献者向けのガイドラインをまとめました。 + +* [プロジェクトの概要](#project-overview) +* [コーディング規約](#coding-conventions) +* [一般的なガイドライン](#general-guidelines) +* [行動規範は私にとって何を意味しますか？](#what-does-the-code-of-conduct-mean-for-me) + +## この全てを読みたくはありません！単純に質問があります！ + +QMK について質問したい場合は、[OLKB Subreddit](https://reddit.com/r/olkb) あるいは [Discord](https://discord.gg/Uq7gcHh) ですることができます。 + +以下の事を覚えておいてください: + +* 誰かがあなたの質問に答えるのに数時間掛かるかもしれません。しばらくお待ちください！ +* QMK に関わる全ての人が彼らの時間とエネルギーを提供しています。QMK に関する作業や質問への回答に対する報酬はありません。 +* できるだけ簡単に答えられるように質問してみてください。その方法が分からない場合は、以下に幾つかの良いガイドがあります: + * https://opensource.com/life/16/10/how-ask-technical-questions + * http://www.catb.org/esr/faqs/smart-questions.html + +# プロジェクトの概要 :id=project-overview + +QMK は主に C で書かれており、特定の機能と部品は C++ で書かれています。QMK は、キーボードの中の組み込みプロセッサ、特に AVR ([LUFA](http://www.fourwalledcubicle.com/LUFA.php)) と ARM ([ChibiOS](http://www.chibios.com)) を対象にしています。すでに Arduino プログラミングに精通している場合は、多くの概念と制限がおなじみのものです。QMK に貢献するには Arduino を使用した経験は必要ありません。 + +<!-- FIXME: We should include a list of resources for learning C here. --> + +# どこで助けを得られますか？ + +助けが必要であれば、[issue を開く](https://github.com/qmk/qmk_firmware/issues) か [Discord で会話する](https://discord.gg/Uq7gcHh)ことができます。 + +# どうやって貢献することができますか？ + +以前にオープンソースに貢献したことはありませんか？ QMK で貢献がどのように機能するかが疑問ですか？ ここに簡単な説明があります！ + +0. [GitHub](https://github.com) アカウントにサインアップします。 +1. 貢献するためのキーマップをまとめるか、解決に興味がある[問題を見つける](https://github.com/qmk/qmk_firmware/issues)、あるいは追加したい[機能](https://github.com/qmk/qmk_firmware/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)を見つけます。 +2. 問題に関連付けられているリポジトリをあなたの GitHub アカウントにフォークします。これは、`GitHub上のあなたのユーザー名/qmk_firmware` の下にリポジトリのコピーを持つことを意味します。 +3. `git clone https://github.com/GitHub上のあなたのユーザー名/repository-name.git` を使ってローカルマシンにリポジトリをクローンします。 +4. 新しい機能に取り組んでいる場合は、issue を開きこれから行う作業について話し合うことを検討してください。 +5. `git checkout -b branch-name-here` を使って修正用の新しいブランチを作成します。 +6. 解決しようとしている問題、あるいは追加したい機能について適切な変更を加えます。 +7. `git add insert-paths-of-changed-files-here` を使って変更されたファイルの内容を git がプロジェクトの状態を管理するために使用する "snapshot"、インデックスとしても知られている、に追加します。 +8. `git commit -m "Insert a short message of the changes made here"` を使って、説明的なメッセージとともにインデックスの内容を保存します。 +9. `git push origin branch-name-here` を使って GitHub 上のリポジトリに変更をプッシュします。 +10. プルリクエストを [QMK Firmware](https://github.com/qmk/qmk_firmware/pull/new/master) にサブミットします。 +11. 行われた変更の簡単な説明と、変更に関する問題またはバグ番号を使って、プルリクエストにタイトルを付けます。例えば、issue に "Added more log outputting to resolve #4352" のようなタイトルをつけることができます。 +12. プルリクエストの説明では、行った変更、行ったプルリクエストに存在すると思われる問題、およびメンテナに対する質問を説明します。プルリクエストが完ぺきではない場合(プルリクエストが無い場合)でも問題ありません。レビュワーが問題の修正と改善を手伝います。 +13. プルリクエストがメンテナによってレビューされるのを待ちます。 +14. レビューをしているメンテナが変更を推奨する場合は、プルリクエストに変更を加えます。 +15. プルリクエストがマージされた後で成功を祝います！ + +# コーディング規約 :id=coding-conventions + +私たちのスタイルのほとんどは簡単に理解できます。C あるいは Python のいずれかに精通している場合は、ローカルスタイルにそれほど問題はないはずです。 + +* [コーディング規約 - C](ja/coding_conventions_c.md) +* [コーディング規約 - Python](ja/coding_conventions_python.md) + +# 一般的なガイドライン :id=general-guidelines + +QMK には幾つかの異なるタイプの変更があり、それぞれ異なるレベルの厳密さが必要です。どのような種類の変更を行っても、次のガイドラインに留意してください。 + +* PR を論理単位に分割します。例えば、2つの個別の機能をカバーする1つの PR を送信するのではなく、代わりに機能ごとに個別の PR をサブミットします。 +* コミットする前に、`git diff --check` を使って不要な空白を確認します。 +* コードの変更が実際にコンパイルされることを確認してください。 + * キーマップ: `make keyboard:your_new_keymap` がエラーを返さないことを確認してください。 + * キーボード: `make keyboard:all` がエラーを返さないことを確認してください。 + * コア: `make all` がエラーを返さないことを確認してください。 +* コミットメッセージがそれ自体で理解できることを確認してください。最初の行に短い説明(70文字以内)を入れ、2行目は空にし、3行目以降では必要に応じてコミットを詳細に説明する必要があります。例: + +``` +kerpleplork の fronzlebop を調整します + +kerpleplork はエラーコード 23 で連続的に失敗していました。根本的な原因は fronzlebop 設定で、これにより kerpleplork はN回の繰り返しごとにアクティブになります。 + +私が使用できるデバイスの限られた実験では、kerpleplork の混乱を避けるために 7 は十分高い値であることを示していますが、念のため ARM デバイスを持つ人たちからフィードバックを得たいです。 +``` + +!> **重要:** デフォルト以外のキーマップ、ユーザスペースおよびレイアウトのようなユーザコードへのバグ修正あるいは改善に貢献したい場合は、PR にコードの元の提出者にタグをつけてください。Git と GitHub のスキルレベルに関係なく、多くのユーザは知らないうちにコードが変更されることに混乱したりイライラしたりするかもしれません。 + +## ドキュメント + +ドキュメントは QMK への貢献を始める最も簡単な方法の1つです。ドキュメントが間違っているか不完全な場所を見つけ、これらを修正するのは簡単です！私たちもドキュメントを編集する人を非常に必要としています。編集するスキルがあるが、どこにどのように飛び乗ればいいのか分からない場合は、[助けをもとめて](#where-can-i-go-for-help)ください！ + +全てのドキュメントは `qmk_firmware/docs` ディレクトリの中にあります。あるいは web ベースのワークフローを使いたい場合は、http://docs.qmk.fm/ の各ページの上部にある "Suggest An Edit" をクリックすることができます。 + +ドキュメントの中にコードの例を提供する場合は、ドキュメント内の他の場所で使用されている命名規則を順守してください。例えば、一貫性を保つために、`my_layers` あるいは `my_keycodes` として列挙型を標準化します: + +```c +enum my_layers { + _FIRST_LAYER, + _SECOND_LAYER +}; + +enum my_keycodes { + FIRST_LAYER = SAFE_RANGE, + SECOND_LAYER +}; +``` + +### ドキュメントのプレビュー + +開発環境をセットアップした場合は、プルリクエストを開く前に以下のコマンドを `qmk_firmware/` フォルダから実行することで、あなたの変更をプレビューすることができます: + + ./bin/qmk docs + +または、Python 3 のみがインストールされている場合: + + python3 -m http.server 8936 + +その後、ウェブブラウザで、`http://localhost:8936/` を表示します。 + +## キーマップ + +ほとんどの初めての QMK 貢献者は、個人のキーマップから始めます。キーマップの標準はかなりカジュアルなものにしようとしています(キーマップは結局のところ作成者の性格を反映しています)が、他の人があなたのキーマップを簡単に見つけて学ぶことができるように、これらのガイドラインに従うようにお願いします。 + +* [the template](documentation_templates.md) を使って `readme.md` を書きます。 +* 全てのキーマップの PR は squash されるため、コミットがどのように squash されるかを気にする場合は、自分で行う必要があります。 +* キーマップの PR に機能をまとめないでください。最初に機能をサブミットし、次にキーマップのための2つ目の PR をサブミットします。 +* `Makefile` をキーマップフォルダに含めないでください(もう使われていません)。 +* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) + +## キーボード + +キーボードは QMK の存在理由です。一部のキーボードはコミュニティによって管理されていますが、他のキーボードはそれぞれのキーボードを作成する責任者によって管理されています。`readme.md` を見るとそのキーボードを管理しているのが誰かが分かります。特定のキーボードに関する質問がある場合、[Issue を開いて](https://github.com/qmk/qmk_firmware/issues)質問にメンテナをタグ付けしてください。(訳注: タグ付け は [メンションする](https://help.github.com/ja/github/writing-on-github/basic-writing-and-formatting-syntax#mentioning-people-and-teams) という意味です。) + +また以下のガイドラインに従うことをお願いします: + +* [the template](ja/documentation_templates.md) を使って `readme.md` を書きます。 +* コミットの数を適切に保ってください。そうでなければあなたの PR を squash します。 +* コア機能を新しいキーボードにまとめないでください。最初に機能をサブミットし、次にキーボード用に別の PR をサブミットしてください。 +* `.c`/`.h` ファイルにすぐ上の親フォルダに従って名前を付けます。例えば、`/keyboards/<kb1>/<kb2>/<kb2>.[ch]` +* `Makefile` をキーボードフォルダに含めないでください(もう使われていません) +* ファイルヘッダの著作権を更新します (`%YOUR_NAME%` を探します) + +## Quantum/TMK コア + +新しい機能をビルドするために多くの作業を行う前に、最適な方法で実装していることを確認する必要があります。[QMK の理解](ja/understanding_qmk.md)を読むことで、QMK の基本的な理解を得ることができます。これはあなたを QMK のプログラムフローのツアーに連れて行きます。ここから、あなたのアイデアを実装するための最良の方法の感覚をつかむために、私たちと話す必要があります。これを行うには主に2つの方法があります: + +* [Discord でのチャット](https://discord.gg/Uq7gcHh) +* [Issue を開く](https://github.com/qmk/qmk_firmware/issues/new) + +機能とバグ修正の PR は全てのキーボードに影響します。また、私たちは QMK の再編も進めています。このため、実装が行われる前に特に重要な変更について議論することが特に重要です。最初に私たちと話をせずに PR を開いた場合、あなたの選択が私たちの計画した方向とうまく合わない場合は幾つかの大きな再作業を行う覚悟をしてください。 + +機能やバグの修正に取り組む時に留意すべき幾つかの事があります。 + +* **デフォルトで無効** - QMK がサポートするほとんどのチップでメモリがかなり制限されており、現在のキーマップが壊れていないことが重要です。ですので、あなたの機能をオフにするのではなく**オン**にするようにしてください。デフォルトでオンにすべき場合、あるいはコードのサイズを小さくする必要がある場合は、相談してください。 +* **サブミットする前にローカルでコンパイル** - これが明白であることを願っていますが、コンパイルする必要があります。私たちの Travis システムは全ての問題をキャッチしますが、結果が返ってくるのを待つ代わりに幾つかのキーボードをローカルでコンパイルする方が一般的に速いです。 +* **リビジョンと異なるチップベースを考慮** - 僅かに異なる設定、さらには異なるチップベースを可能にするリビジョンを持つキーボードが幾つかあります。ARM および AVR でサポートされる機能を作成する、あるいは動作しないプラットフォームでは自動的に無効化するようにしてください。 +* **機 |