README と 1 つのコマンドでの実行
きれいな配置と本物のテストがそろいました。最後のひと区切りは、レビューする人が実際に最初にぶつかる部分です:README と、それを実行する 1 つのコマンドです。始めるのに 10 分も推測が必要なプロジェクトは、動いていても壊れているように感じられます。クローンして 1 行で実行できるプロジェクトは、小さくてもプロらしく感じられます。同じコード -> まったく違う印象です。
README は約束です。読む人は上から下へ流し読みし、予測できる形を期待します:タイトルとしてのプロジェクトの名前、次にインストールの仕方、次に使い方、次にテストの仕方。具体的には、強い README は最上位のタイトルの行(# Something)を持ち、それから次の節をこの順番で持ちます:
# Triage Copilot
## Setup
pip install -e . # editable install
cp .env.example .env # then paste your real key into .env
## Usage
python -m triage # the one-command run
## Tests
pytest
読む人はそれを手順としてたどるので、順番が大切です。Setup の前に Usage があると混乱します -> インストールしていないものは使えません。だから確認関数 validate_readme(text) を書きます。# のタイトルが現れ、そのあとに ## Setup、次に ## Usage、次に ## Tests が、それぞれ前のもののあとに現れるときだけ True を返します。節が欠けているか順番が違えば False を返します。コツ:行を 1 回たどり、今どこにいるかの「カーソル」を持ち、各節がカーソルより後ろの位置に現れることを求めるのです。
1 つのコマンドでの実行。上の ## Usage の行が 1 つのコマンドであることに注目しましょう。それが make run のような Makefile や justfile のターゲットの目標です -> プロジェクトを立ち上げる、覚えやすい 1 つのコマンドで、誰も完全な呼び出し方を覚えておく必要がありません。プロジェクトについてそのコマンドの文字列を返す make_run(name) を書いてください。たとえば python -m triage(あるいは make run)です。違うプロジェクトなら違うコマンドになるように、パッケージのディレクトリと同じやり方で正規化したプロジェクトの名前を埋め込まなければなりません。
本物のリポジトリのための、正直な、採点しない注記を 2 つ。1 つ目に、秘密情報:cp .env.example .env のステップがあるのは、本物の API キーは .env に入れ、それを .gitignore に加えて決してコミットしないからです。コミットするのは .env.example だけです -> 置き場所の値を入れた設定の形です。公開リポジトリにキーを漏らすのは、ポートフォリオのプロジェクトの典型的な間違いです。2 つ目に、これのデプロイ:オンラインに載せるには、小さな Dockerfile を書き(リポジトリをコピーし、pip install し、実行コマンドをエントリーポイントに設定する)、Render、Railway、Fly のような PaaS に push します。その部分はブラウザでは実行も採点もできません -> 公開するときにあなたがすることです。実行を押して、完全な README を検証し、実行コマンドを出力しましょう。
良い README の決定的な部品を 2 つ書いてください。validate_readme(text) は、最上位の # のタイトルが現れ、次に ## Setup、次に ## Usage、次に ## Tests が、それぞれ前のもののあとに現れるときに限り True を返します(節が欠けているか順番が違えば -> False)。make_run(name) は、パッケージのディレクトリと同じように正規化したプロジェクトの名前を埋め込んだ 1 つのコマンドでの実行の文字列(例:python -m <pkg> か make run)を返すので、違う名前なら違うコマンドになります。
この演習はまもなく開きます
その前のレッスンを終えると、このレッスンが解放されます。コース全体が無料でアカウントも不要、このレッスンは今すぐ読めます。
このブラウザは learn.floati.life の Cookie をブロックしているため、ここで修了したレッスンを順番どおりに開けません。このサイトの Cookie を許可して再読み込みしてください。