pdoc3で超お手軽にPythonコードのドキュメントを生成しよう

Pythonのドキュメンテーションシステムといえばsphinxが有名ですが、もっとお手軽にできてしまうpdoc3を紹介してみます。

※本記事の情報は2020年11月30日、pdoc3 v0.9.2時点の情報になります。

TL;DR

• pdoc3で設定なしでお手軽ドキュメンテーション生成！
• こんな感じの美しいサイトを生成できるよ
  • https://yukinarit.github.io/pyserde/

pdoc3

• Webサイト: https://pdoc3.github.io/pdoc/
• APIドキュメント: https://pdoc3.github.io/pdoc/doc/pdoc/
• PyPI: https://pypi.org/project/pdoc3/
• Github: https://github.com/pdoc3/pdoc/

特徴・機能一覧

• 設定なしでも簡単に動く
• docstring(Markdown, numpydoc, Google-style)、LaTex math、reSTをサポート
  • 例えばreSTのincludeで別のMarkdownをインクルードできたりする
• PEP484やPEP526といったクラスや変数に対する型宣言を表示してくれる
• サイト内Google検索の設置
• デザインテンプレートのカスタマイズ
• Lunrによる全文検索
• ビルトインのHTTPサーバー

Sphinxとの違い

SphinxはPythonソースコードからのAPIドキュメンテーション生成だけでなく、reSTやMarkdownからのドキュメンテーション生成もサポートしている。

一方、pdoc3はソースコードからのAPIドキュメンテーション生成だけしかできない。もし、Markdown等から生成したい場合は、MkDocs、GitBookやmdBookをセットで使いましょう。筆者はRustaceanなので、mdBookを愛用しています。

使い方

前置きが長くなりましたが、早速使ってみましょう。

pip install pdoc3

--htmlでHTM形式で出力（デフォルトではMarkdown, --pdfでMarkdown-PDF変換用のMarkdown形式になる)

pdoc <Module名> --html -o <出力ディレクトリ>

--forceで強制上書き

pdoc <Module名> --html -o <出力ディレクトリ> --force

HTTP用サーバーを立ち上げる

pdoc <Module名> --html -o <出力ディレクトリ> --force --http <IPアドレス:Port>

こんな感じで出来上がります

• pdoc3本家のdocs: https://pdoc3.github.io/pdoc/doc/pdoc/
• 筆者のライブラリのdocs: https://yukinarit.github.io/pyserde/

Tips

ドキュメントにCIのバッジ付ける

README.mdにはCIのバッジとか付けていたら、ルートの__init__.pyで.. include:: ../README.mdするとドキュメントにも表示することができる

"""
.. include:: ../README.md
"""
from .core import SerdeError, init, logger, typecheck  # noqa
from .de import deserialize, from_dict, from_obj, from_tuple, is_deserializable  # noqa
from .se import asdict, astuple, is_serializable, serialize  # noqa

グローバル変数のドキュメント

変数の下にコメントを付けましょう。下である必要があります。

FOO_VAR = xxx
""" This is VAR of FOO"""

ドキュメント化したくない場合

• モジュール内に__all__変数を作り、そこにドキュメント化したい変数だけ列挙する

__all__ = [
    'serialize',
    'deserialize',
]

• __all__を作りたくない場合は、pdoc3が提供する__pdoc__変数でも制御可能。詳しくはこちら

ドキュメント内にGoogle検索バーを追加する

config.makoに以下の変数を作り、検索クエリを指定する。クエリに使えるシンタックスはこちらを参照

google_search_query = 'inurl:github.com/USER/PROJECT site:PROJECT.github.io site:PROJECT.website'

pdocコマンド実行時に--template-dirでconfig.makoのあるディレクトリを指定してやれば良い

pdoc <Module名> --html -o <出力ディレクトリ> --force --template-dir <config.makoのあるディレクトリ>

Github Actionsでドキュメントをgithub.ioにアップロードする

github-pages-deploy-actionを使えば簡単にアップロードできる。

例として筆者のプロジェクトでは、以下のようなActionを実行している。参考にされたし。

• PR番号を取得
• ドキュメントのビルド
• コミットメッセージにPR番号をいれる
• gh-pagesブランチにプッシュ

まとめ

pdoc3を使えば超簡単にドキュメントを生成、公開できるのでみんなもやってみよう。