PythonパッケージにREADMEファイルを追加する#

前回のレッスンであなたは以下のことを学びました:

  1. Pythonパッケージとは何か?

  2. コードをインストール可能にする

  3. (test) PyPIにパッケージを公開する方法

  4. パッケージをconda-forgeに公開する方法

学習目標

このレッスンで学ぶこと:

  1. パッケージに README.md ファイルを追加する方法。

  2. README.md ファイルの核となる要素は何か。

README ファイルとは何か？#

README.md ファイルはプロジェクトディレクトリのルートにあるマークダウンファイルで、ユーザーの理解を助けるものです:

  • パッケージ名

  • パッケージが何をするのか。 READMEファイルには、あなたのソフトウェアが解決するために設計された(複数の)問題と、その対象読者を明確に記述してください。

  • パッケージの現在の開発 "状態" （バッジを通して）

  • パッケージの使い始め方

  • パッケージに貢献する方法

  • パッケージの引用方法

README.md ファイルは、誰かがあなたのパッケージをインストールする前に、最初に目にすることが多いので重要です。 READMEファイルはPyPIのランディングページに入力するためにも使われます。

READMEファイルには特定のコンテンツ構造はないことに注意してください。 しかし、このチュートリアルでは、READMEファイルに含めることを推奨するセクションの概要を説明します。

パッケージの README.md ファイルを作成する#

README.md ファイルをプロジェクト・ディレクトリに追加しましょう。

ステップ0: READMEファイルの作成#

まず、プロジェクトディレクトリにまだREADME.mdファイルがない場合は、作成してください。

Tip

以下からプロジェクトディレクトリを作成した場合

  • オンラインのGitHubリポジトリ

  • hatch init を使用する。

その場合、プロジェクトディレクトリに README.MD ファイルが既にあるかもしれません。

ステップ1: READMEのタイトルにパッケージ名を追加する#

README.md ファイルの先頭に、パッケージ名を追加します。

マークダウンを使用している場合は、 # 記号1つで示されるヘッダー1 (H1) タグでなければなりません。

# Package-title-here

ステップ2: READMEファイルの先頭にバッジを追加する#

メンテナが README ファイルの先頭にバッジを追加するのはよくあることです。 バッジをつけることで、あなたとあなたのパッケージのユーザは以下のようなことを追跡できるようになります:

  • ドキュメントとテストビルドが壊れています。

  • PyPIとcondaにあるあなたのパッケージのバージョン。

  • あなたのパッケージがpyOpenSciやJOSSのような組織によってレビューされ、審査されたかどうか。

すでにpypi.orgにパッケージを公開している場合は、 shields.ioでパッケージのバージョンバッジを作成 することができます。 このバッジは、あなたが新しいバージョンのパッケージをPyPIにリリースすると動的に更新されます。

そうでない場合は、今のところ上部を空にしておいて、後でREADMEにバッジを追加することができます。

ステップ 3: パッケージの説明を追加する#

バッジの下に（バッジがある場合）、あなたのパッケージが何をするのかをわかりやすく説明するテキストのセクションを追加します。

  • このセクションは短めにしてください。

  • 専門用語はなるべく避けてください。

  • 説明をより多くの人が理解できるように、使用する専門用語を定義します。

あなたのパッケージが何をするものなのか、より多くの人が理解すればするほど、より多くの人がそれを使うようになることを忘れないでください。

ステップ4: パッケージのインストール方法を追加する#

次に、ユーザーにパッケージのインストール方法を説明するインストラクションを追加します。

例えば、彼らはあなたのパッケージをインストールするためにpipを使うことができますか？ python -m pip install packagename

それともconda？

conda install -c conda-forge packagename`.

まだパッケージをpypi.orgに公開していない場合は、このセクションを読み飛ばして、後でこれらの説明を追加してください。

ステップ5：追加設定#

場合によっては、あなたのパッケージを使用するために、あなたのパッケージのユーザーが他のツールを手動でインストールする必要があるかもしれません。 その場合は、READMEファイルに追加セットアップのセクションを追加してください。

ここで、あなたのパッケージを使うために必要な追加設定を簡単に文書化 (または文書へのリンク) をしてください。これには以下が含まれます:

  • 認証情報、あなたのパッケージに適用される場合。

  • GDALのような追加ツールのインストール。

注釈

多くのパッケージでは、READMEに追加のセットアップセクションは必要ありません。 その場合、このセクションはいつでも読み飛ばすことができます。

ステップ6: スタートセクションの追加#

次に、get-started セクションを追加します。 このセクションに、パッケージの機能の一部をインポートして使用することを示す、小さなコード例を追加します。

可能であれば、完全に機能するコードスニペットを提供してください。

ユーザーに提供するコード例は、できるだけ役立つものにするよう努めることが重要です。

可能であれば、Jupyter Notebookや.pyファイルに貼り付けてもそのまま動作するようなコピー＆ペーストのコード例を必ず提示してください。

あなたのパッケージを実行するために必要なトークンや他のステップがある場合、それらのステップが何であるかを明確にするようにしてください。

pyosPackageの場合、簡単に始めるデモは次のようになります:

>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3

あるいは、あなたが作成したチュートリアルへのリンクでもかまいません。 まだチュートリアルをお持ちでない場合は、当分の間、空欄のままにしておいてください。

また、一般的なワークフローでのパッケージの使い方を理解するのに役立つチュートリアルへのリンクを追加するのにも最適な場所です。

ステップ7: コミュニティセクション#

READMEファイルのコミュニティセクションは、あなたのプロジェクトに参加したいユーザーのための情報を含める場所です。 この参加は、おそらく GitHub や GitLab のようなプラットフォームで行われるでしょう。

コミュニティセクションでは、あなたの貢献ガイドと CODE_OF_CONDUCT.md へのリンクを追加します。 次のレッスンでは CODE_OF_CONDUCT.md ファイル を作成することになります。

パッケージが大きくなるにつれて、貢献者やメンテナチームが従う開発ガイドへのリンクを持つこともできます。この開発ガイドには、次のようなメンテナンス作業の方法が概説されています:

  • テストの実行

  • パッケージのリリース

  • ドキュメントの作成

  • などなど。

ステップ8: 引用情報#

最後に、ユーザーにあなたのパッケージの引用方法を知らせることが重要です。 引用情報を伝える方法はいくつかあります。

GitHubのようなプラットフォームでホストされている場合、zenodoのようなツールを使ってパッケージのDOIと関連する引用情報を作成することができます。 この短いチュートリアルで、その設定をチェックしてみましょう。

あるいは、 pyOpenSciが主導するような査読プロセスを通して パッケージを送ることもできます。 pyOpenSciに受理された後、あなたのパッケージがスコープ内であれば、Journal of Open Source Softwareに受理され、 Journal of Open Source Softwareとの提携により 相互参照DOIを得ることができます。

完成したREADMEファイル#

完成した README.md ファイルは次のようになるはずです:

# pyosPackage

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8365068.svg)](https://doi.org/10.5281/zenodo.8365068)
[![pyOpenSci](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-review/issues/115)

## What pyosPackage does

Short description here using non-technical language that describes what your package does.

## How to install pyosPackage

:::{todo}
- when i add more to the pyos package this can use that readme>
:::

To install this package run:

`python -m pip install pyosPackage`

## OPTIONAL - if you have additional setup instructions add them here. If not, skip this section.

## Get started using pyosPackage

Here add a quick code demo showing a user how to use the package after it is installed.

```python
>>> from pyospackage.add_numbers import add_num
>>> add_num(1, 2)
3

```

You can also add any links to tutorials in your documentation here.

## Community

Add information here about contributing to your package. Be sure to add links to your
`CODE_OF_CONDUCT.md` file and your development guide. For now this section might be
empty. You can go back and fill it in later.

## How to cite pyosPackage

citation information here

まとめ#

README.md ファイルを作成する際には、新しいユーザーや貢献者が必要とするかもしれない情報を考慮することが重要です。 完璧なテンプレートは存在しないが、上記はこれから始めようとしているあなたへの推奨事項です。 あなたがパッケージをさらに開発し、コミュニティがあなたのパッケージを使い始めるにつれて、このファイルに他の要素を追加する必要性が出てくるかもしれません。

次のレッスン では、 LICENSEファイルをPythonパッケージに追加します。 ライセンスファイルは、ユーザーがあなたのパッケージを合法的にどのように使うことができるのか（そして使うことができないのか）を示す重要なものです。また:

  • ユーザーとの信頼関係を築く

  • パッケージと関連コードの悪用を防ぐ