pydoc 超入門

• 概要
• 環境
• サンプルコード
• ドキュメント生成
• 残念な点
• 最後に
• 参考サイト

概要

Python の標準で付属されている pydoc を使ってみました
docstring は Google Style Guide を参考にしています

環境

• macOS 10.15.5
• Python 3.7.3

サンプルコード

• vim module/__init__.py

"""
main.py
"""
from module import TestClass

if __name__ == '__main__':
    tc = TestClass("Hello")
    tc.say("Python!")

• vim main.py

from datetime import datetime
"""
This is a test module.
"""

__author__  = "hawksnowlog <hawksnowlog@gmail.com>"
__version__ = "0.1.0"
__date__    = datetime.now()

class TestClass:
    """
    This is a test class

    Attributes:
      default_msg (str): Default message
    """

    def __init__(self, default_msg):
        """
        Constructor

        Args:
          default_msg (str): Default message
        """
        self.default_msg = default_msg

    def say(self, msg):
        """
        Print a message

        Args:
          msg (str): A message you like
        Returns:
          None
        Raises
          None
        """
        print("%s, %s" % (self.default_msg, msg))

これらを実行する方法以下の通りです

• python3 main.py

ドキュメント生成

作成したソースコードからドキュメントを生成します

• python3 -m pydoc -w main module

.py などの拡張子は指定しません
-w で HTML ファイルを出力します
生成される HTML ファイルは以下の通りです

Package Contents はサブディレクトリがある場合に出力されます
例えば module/sub/__init__.py がある場合に表示されます

残念な点

• Data descriptors defined here: の部分を変更する方法が不明
• index.html は出力されない
• 外部のクラスなどにリンクできない (参考)
• docstring と呼ばれるドキュメントの書き方がたくさんあるのでどれを選択すればいいのかわからない

最後に

Python 標準のドキュメントツール pydoc を使ってみました
rdoc や yard に比べるとちょっと機能が劣りますが簡単に使えるのは良い点かなと思います
Sphinx を使えばデザインなども設定できますがいろいろと準備が必要なのが難点です

参考サイト

• http://google.github.io/styleguide/pyguide.html#381-docstrings