개요

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"),
    ... # その他の項目は省略
)

위의 절차로 패키지를 등록하면 다음과 같이 무사히 렌더링됩니다.