READMEファイルのガイドラインとリソース#
README.md ファイルは、GitHubリポジトリのルートに置く必要があります。 README.md ファイルは、あなたのパッケージをインストールする前に誰かが最初に目にすることが多いので重要です。
README.mdファイルは、そのランディングページです:
PyPIやAnaconda.orgのようなリポジトリサイトに表示されているあなたのパッケージ
あなたのパッケージのGitHubリポジトリ
あなたのREADME.mdファイルは、以下のようなサイトで、パッケージやコミュニティの健全性の指標としても使われています:
GitHub community health for MovingPandas (available for all repositories) and Snyk - MovingPandas example
GitHub リポジトリのランディングページは README.md ファイルをハイライトします。ここでは、pyOpenSciパッケージ Pandera のREADME.mdファイルを見ることができます。 (スクリーンショットは2022年11月23日撮影) 。#
従って、Pythonパッケージのために高品質の README.md ファイルを作成するために、前もって時間をかけることが重要です。
注釈
READMEファイルが以下に指定された基準を満たしていない場合、編集者または編集長はレビュー開始前に修正を依頼します。
あなたのパッケージをpyOpenSciに投稿する前に、このリストに目を通してください。
### pyOpenSci README checklist
Your README file should have the following information:
- [ ] The name of the package
- [ ] Badges for the packages current published version, documentation and test suite build. (OPTIONAL: test coverage)
- [ ] Easy-to-understand explanation (2-4 sentences) of what your tool does
- [ ] Context for how the tool fits into the broader ecosystem
- [ ] If your library/package "wraps" around another package, link to the package that it is wrapping and any associated documentation. *(HINT: If you don't know what a wrapper is, this probably doesn't apply to you!)*
- [ ] A simple quick-start code example that a user can follow to provide a demonstration of what the package can do for them
- [ ] Links to your package's documentation / website.
- [ ] A few descriptive links to any tutorials you've created for your package.
README.mdファイルの内容#
README.md ファイルには、（上から順番に）以下のことが書かれているはずです：
✔️ パッケージ名#
GitHub リポジトリの名前がパッケージの名前にもなっているのが理想的です。 説明しやすい名前であればあるほどよいでしょう。
✔️ 現在のパッケージバージョン、継続的インテグレーション、テストカバレッジのバッジ#
バッジは、あなたのプロジェクトの品質に注意を向けるための便利な方法です。 バッジは、あなたのパッケージがよく設計され、テストされ、保守されていることをユーザに保証します。 また、適切にビルドされているかどうかを評価するのに便利なメンテナンスツールでもあります。 README.mdファイルに Read the Docs status badge を追加することで、そのサイトのビルドが失敗したときにすぐに確認することができます。
READMEファイルの一番上に、他の人がすぐに閲覧できるようにバッジのコレクションを提供するのが一般的です。
READMEファイルへの追加を検討すべきバッジには、以下のようなものがあります:
PyPI / Anaconda.org にあるパッケージの最新バージョン
例: 
テストのステータス(合格または不合格) - 例:
ドキュメントのビルド - 例:
(参照のための) DOI の例:
Tip
あなたのパッケージがpyOpenSciに受理されると、あなたのリポジトリにレビュー済みであることを示すバッジを提供します。 
注意
バッジの使い過ぎに注意！ 過ぎたるは及ばざるが如し(潜在的なユーザーを過負荷にする可能性があります!)。
✔️ あなたのパッケージが何をするのかを短く、わかりやすく説明する。#
READMEファイルの一番上に、あなたのパッケージが何をするのか、短く、わかりやすく、1-3文の説明を書くべきです。このセクションには、パッケージの目標を明記します。この説明では、科学的（および開発的）背景が異なるさまざまなユーザーが理解できるように、専門用語をあまり使わないようにすべきです。
この説明では、あなたのパッケージがより広い科学的 Python パッケージのエコシステムの中でどのように位置づけられるかをユーザに知らせるのに役立ちます。 もし他に似たようなパッケージや補完的なパッケージがあれば、ここで1-2文でそれらに言及してください。
Tip
高校レベル（または同等のレベル）の文章を書くことを考慮します。 このレベルの文章は、さまざまな背景を持つさまざまなユーザーに役立つ科学的な内容として、しばしば適切なレベルとみなされます。
この記述の目的は、 README ファイルへのアクセシビリティを最大化することです。
✔️ インストール手順#
パッケージのインストール手順を含めます。 PyPIとAnaconda.orgの両方でパッケージを公開している場合は、必ず両方の説明を含めてください。
✔️ 必要な追加設定を文書化する#
認証トークンなど、パッケージの使用を開始するために必要な追加設定を追加します。 セットアップが複雑な場合は、READMEファイルを複雑にしすぎるのではなく、オンラインドキュメントのインストールページにリンクすることを検討してください。
✔️ パッケージの使い方の簡単なデモンストレーション#
この説明には、あなたのパッケージを使い始める方法をユーザーに示す、簡単なクイックスタートコードの例が含まれているのが理想的です。
✔️ パッケージドキュメントへの説明的なリンク、短いチュートリアル#
説明的なリンクを含める:
パッケージのドキュメントページ。
パッケージのアプリケーションをデモンストレーションする短いチュートリアル。
良いことのあまり
README.mdファイル自体に複数のチュートリアルを含めるのはなるべく避けてください。 これもユーザーを情報で圧倒してしまいます。
READMEファイルの内容は、あなたのパッケージの使い方を示す短いクイックスタートのコード例で十分です。 他のすべてのチュートリアルやドキュメントは、説明的なリンクとして表示されるべきです。
✔️ 貢献ガイド、行動規範へのリンクがあるコミュニティセクション#
README.mdファイルを使用して、ユーザーをより詳細な情報に誘導する:
パッケージへの貢献
より高度な技術貢献者のための開発セットアップ
あなたの行動規範
ライセンス情報
上記のファイルはすべて、あなたのプロジェクトを取り巻くコミュニティを構築するために重要です。
✔️ 引用情報#
最後に、パッケージの引用方法を必ず明記してください。引用には、パッケージを引用する際に使用してほしいDOIと、引用に関連する言語を含めてください。
READMEリソース
以下に、優れたREADME.mdファイルを作成するためのリソースをいくつか紹介するので、参考にしてください。