PythonパッケージをPyPIにアップロードする際にMarkdownをreSTに変換

MarkdownフォーマットではHTML描画されない問題

Pythonパッケージの開発もGitHubが使われるケースが増えている。それに伴って、パッケージのドキュメントもMarkdownフォーマットが採用されるケースも散見される。

ただし、MarkdownフォーマットでPyPIサーバーにアップロードすると、Web UIではHTML描画されないため、ユーザーフレンドリーではない。

そこで、Pythonパッケージの新しいバージョンをPyPIサーバーにアップロードする際に、オンデマンドでreStructuredText（以降「reST」）フォーマットにオンデマンドで変換してやると、いい感じにWeb UIでもHTML描画される。

環境準備

フォーマットのオンデマンド変換には、ドキュメントコンバーターであるPandocと、そのPythonラッパーであるpypandocを利用する。この変換Tipsは、pypandoc自身でも新バージョンのリリース時に採用されている手法である。

Pandocの準備は、Installing pandocの項を参考に、ビルド済みバイナリでインストールする。macOSであればHomebrew、Linuxであればディストリビューションごとのパッケージ管理ツール経由でインストールできる。

pypandocはPyPIサーバから pip install でインストールする。

$ pip install pypandoc

変換処理の適用

パッケージのドキュメントが README.md というファイル名で管理されていると仮定すると、setup.py に適用する変換処理は次のようになる。

import os
from setuptools import setup


def read_file(filename):
    basepath = os.path.dirname(os.path.dirname(__file__))
    filepath = os.path.join(basepath, filename)
    if os.path.exists(filepath):
        return open(filepath).read()
    else:
        return ''


LONG_DESC = ''
try:
    import pypandoc
    LONG_DESC = pypandoc.convert('README.md', 'rst', format='markdown_github')
except (IOError, ImportError):
    LONG_DESC = read_file('README.md')


setup(
    name='your-package-name',
    long_description=LONG_DESC,
    # (省略)
)

これで毎回 setup.py でパッケージを作成した際に long_description として渡されるドキュメントはreSTフォーマットに変換済みとなった。

ただしPandocの変換も完全ではないため、壊れたreSTフォーマットになってしまう時がある。

壊れた状態でPyPIにアップロードしてもHTML描画されないため、気になる時は dist/ ディレクトリの成果物をチェックしておくと良い。 rst2html.py はdocutilsパッケージに付属している。

$ python setup.py --long-description | rst2html.py > /dev/null

上記のコマンドでエラーが出力されなければ、PyPIへ成果物アップロード後、整形されたHTMLで描画される。

もちろん、最初から README.rst としてreSTフォーマットでドキュメント管理していれば、こういうTipsは不要だが、GitHubで新しいリポジトリを作成した時のデフォルトはMarkdownフォーマットであり、Markdownの方が慣れている開発者も多いため、オンデマンド変換も悪くないやり方と思われる。

参考情報

• Use Markdown README's in Python modules (Example)
• Python Package Index (PyPI)