PyPI によく合う README を作る#

README ファイルは、あなたのパッケージのユーザがプロジェクトを理解するのを助け、プロジェクトの説明をするのに使われています。このガイドでは、PyPI によく合う形で README を作成するのを助け、あなたのパッケージの README が PyPI で表示されるようにします。

README ファイルを作成する#

Python プロジェクトにおける READMEファイルは、しばしば README ・ README.txt ・ README.rst ・ README.md などと命名されます。

あなたの README を PyPI で正しく表示するためには、PyPI がサポートするマークアップ言語を選択する必要があります。 PyPI の README レンダラとしてサポートされているのは:

プレーンテキスト
reStructuredText (Sphinx 拡張なし)
マークダウン (デフォルトでは GitHub Flavored Markdown 、あるいは CommonMark)

README ファイルについては、 setup.py ファイルと同様にプロジェクトのルートディレクトリに置くのが慣習になっています。

README にパッケージのメタデータを含ませる#

README の内容をパッケージの説明として引用させるには、典型的にはプロジェクトの setup.py ファイルに、プロジェクトの Description と Description-Content-Type のふたつのメタデータを設定しておきましょう。

参考

例えば、これらの値をパッケージの setup.py ファイルに設定するためには、 setup() の long_description と long_description_content_type を使ってください。

long_desctription には README ファイルの内容それ自体 (パスではなく) を設定してください。 long_description_content_type には、README ファイルのマークアップの型を受け入れ可能な Content-Type 風の書き方、すなわち text/plain ・ text/x-rst (reStructuredText の場合) ・ text/markdown から選んで設定してください。

注釈

プロジェクトの説明を GitHub 方言のマークダウンで書くのであれば、以下のツールを更新しておくことを忘れないでください:

Unix/macOS

python3 -m pip install --user --upgrade setuptools wheel twine

Windows

py -m pip install --user --upgrade setuptools wheel twine

各ツールは少なくとも次のバージョンでなければなりません:

setuptools >= 38.6.0
wheel >= 0.31.0
twine >= 1.11.0

プロジェクトの配布物パッケージをアップロードする時は twine を使うことを推奨します。

twine upload dist/*

例えば、この setup.py ファイルでは、 README.md の内容を読み取って long_description としていて、マークアップ方式は GitHub 方言のマークダウンを指定しています:

from setuptools import setup

# read the contents of your README file
from pathlib import Path
this_directory = Path(__file__).parent
long_description = (this_directory / "README.md").read_text()

setup(
    name='an_example_package',
    # other arguments omitted
    long_description=long_description,
    long_description_content_type='text/markdown'
)

reStructuredText マークアップを検証する#

README を reStructuredText で書いている場合、無効なマークアップがひとつでもあると描画できないので、PyPI 上では README の生のソースコードを表示するだけになってしまいます。

ディレクティブとロール (例えば ":py:func:`getattr`" や ":ref:`my-reference-label`") のように docstrings 内で使われる Sphinx 拡張はこの場所では使用を許されず、 Error: テキストロール "py:func" が見つかりません。<Unknown interpreted text role "py:func".> といったエラーメッセージを出すことになります。

README ファイルのマークアップに関するエラーをアップロードする前に確認するには、次のようにします:

最新版の twine をインストールします; バージョン 1.12.0 またはそれ以上のものが必須です:
Unix/macOS
python3 -m pip install --upgrade twine
Windows
py -m pip install --upgrade twine
あなたのプロジェクトをパッケージするに記述されているように、プロジェクトの sdist と wheel をビルドします。
sdist と wheel に対して twine check を実行します:
```
twine check dist/*
```
このコマンドは README のレンダリングに関する問題があれば報告するでしょう。マークアップのレンダリングに問題がなければ、 配布物を検査しています FILENAME: 合格 <Checking distribution FILENAME: Passed> と出力するでしょう。