新しいPyPIでMarkdownのドキュメントを使う

長い間、Pythonでパッケージを作った場合、構造化されたドキュメントを使う場合は、reStructuredText (reST)でドキュメントを書く必要がありました。

ところが、aodag さんに教えてもらったのですが2018年2月にアクセプトされたPEP 566のおかげで、PyPIのドキュメントがtxtかreSTでなければいけないという制約が外れました。そこで、昨日新しくなったばかりのPyPIでMarkdownがレンダーできる方法を試してみました。

(必要に応じて)ライブラリをupgradeする

Markdownが扱えるようになったのは、setuptoolsのv38.6.0からです。古いバージョンだとMarkdownがレンダーされないので、合わせてpipとwheelをupgradeしておきました。

$ python -m pip install –upgrade pip
$ pip install –upgrade wheel
$ pip –version
pip 10.0.0 from c:\users\chezo\documents\source\tabula-py\venv\lib\site-packages\pip (python 3.6)
$ pip list
Package Version Location
-—————- ———– ————————————–
(…snip…)
setuptools 38.1.0
(…snip…)
wheel 0.31.0

setup.pyを編集する

long_description_content_typeという項目をsetup.pyに追加することで、reST以外の形式を使えるようになります。Markdownであれば例えば以下のようになると思います。

long_description=open(‘README.md’).read(),
long_description_content_type=”text/markdown”,

元々README.mdを読むようにしていたので、今回は long_description_content_type の行を追加するだけで済みました。

実際のPRはこちらです。

wheelを作ってtwineでアップロードする

後はいつもどおりwheelを作ってtwineでPyPIにアップロードしました。なお、

$ python setup.py bdist_wheel
$ twine upload dist/*

今回はこれだけのためにpatch versionを上げるのもなぁということで、test.pypi.orgにあげています。

参考文献

• PEP 566の関連箇所
• https://github.com/pypa/readme_renderer
• https://github.com/pypa/sampleproject/pull/66