PyPIに登録するパッケージの説明文を半自動生成する

3169 ワード
PyPI Python reStructuredText pip Markdown Python テキストリンク

概要

PyPI にパッケージを登録するとき，特に指定しなければ説明文として README.md が使用される．
しかし， Markdown 形式ではレンダリングされないため下記のように醜い文章が表示されることになる．

この説明文は，reStructuredText 形式ならばレンダリングされる．
そこで，README.md から README.rst を生成し，説明文として設定する方法を備忘録として記す．

Markdown から reStructuredText への変換

GitHub 等でコードベースを管理しているならば，README.md は用意されていると考えられるので，
この Markdown テキストを reStructuredText 形式へ変換する．

変換には，Pandoc を使う．

$ pandoc --from markdown --to rst README.md -o README.rst

なお，Pandoc は brew でインストールできる．

$ brew install pandoc

パッケージ情報への登録

README.md と README.rst が両方ともパッケージに含まれている場合，
README.md の方が優先されてしまうので， setup.py で README.rst を説明文として使用するように設定する．

具体的には，setup 関数の long_description キーワード引数に README.rst の内容を渡す．

setup.py
from os import path
from setuptools import setup, find_packages

def read(fname):
    return open(path.join(path.dirname(__file__), fname)).read()

setup(
    long_description=read("README.rst"),
    ... # その他の項目は省略
)

以上の手続きでパッケージを登録すると，下記のように無事レンダリングされるようになる．