このページの内容

Guidedog / ドキュメント 0.2.0

autodoc による Python のドキュメント作成

Guidedog はソースコードを読んで Python のドキュメントを生成します。パッケージはインポートしません。docstring とシグネチャはドキュメントグラフに組み込まれます。実行時にしか作られないオブジェクトは、明示的に記述する必要があります。これは意図的な境界です。

設定

拡張機能を指定し、ソースディレクトリを基準にパッケージの場所を Guidedog に伝えます。Python の sys.path に相当します。

extensions = ["sphinx.ext.autodoc"]
autodoc_source_paths = ["../src"]

guidedog migrate は、sys.path.insert(0, os.path.abspath('..')) など、conf.py がパッケージを探すために使う行から autodoc_source_paths を生成します。別の場所にインストールされたパッケージは、そのディレクトリを追加した場合にだけ見つかります。依存パッケージのソースを取得したディレクトリなどを指定してください。Guidedog は Python 自身の site-packages を検索しません。

各ディレクティブは Sphinx と同じように使えます。

.. automodule:: shop.cart
   :members:
   :show-inheritance:

.. autoclass:: shop.Cart
   :members: add, remove
   :inherited-members:

Sphinx 9.1 の全オプションを同じ意味で受け付けます。:members:、:undoc-members:、:private-members:、:special-members:、:inherited-members:、:exclude-members:、:member-order:、:show-inheritance:、:imported-members:、:ignore-module-all:、:class-doc-from:、:no-value:、:annotation:、:no-index:、:no-index-entry:、:synopsis:、:platform:、:deprecated: と、autodoc_default_options を取り消す no- 形式です。

設定項目

これらの conf.toml 設定は、Sphinx と同じ名前、値、既定値を使います。

autodoc_source_paths

Guidedog 独自の設定です。Python モジュールを探すディレクトリを、ソースディレクトリからの相対パスで検索順に指定します。指定したディレクトリ内のファイルだけを読み、外部に通じるシンボリックリンクは拒否します。

autoclass_content

クラスの説明に使う docstring を指定します。"class"（既定）、"init"、"both" から選びます。

autodoc_class_signature

"mixed"（既定）または "separated"。後者では __init__ をメソッドとして記載します。

autodoc_default_options

すべてのディレクティブに適用するオプションの表です。例は members = true や member-order = "bysource"。値を false にすると、そのオプションを省きます。

autodoc_docstring_signature

true（既定）：docstring の先頭行が name(args) -> result のような形なら、シグネチャとして使います。

autodoc_inherit_docstrings

true（既定）：docstring のないメンバーは基底クラスのものを引き継ぎます。

autodoc_member_order

"alphabetical"（既定）、"groupwise"、"bysource" から選びます。

autodoc_preserve_defaults

false（既定）：既定値を repr() の表現で表示します。true ではソースに書かれた形を使います。

autodoc_typehints

"signature"（既定）、"description"（:type: と :rtype: フィールド）、"both"、"none" から選びます。

autodoc_typehints_description_target

"all"（既定）、"documented"、"documented_params" から選びます。

autodoc_typehints_format

"short"（既定）または "fully-qualified"。

autodoc_use_type_comments

true（既定）：# type: コメントを型注釈として扱います。

strip_signature_backslash

Sphinx と同様に、シグネチャ内のバックスラッシュを二重にします。

autodoc_mock_imports, autodoc_type_aliases, autodoc_warningiserror

設定は受け付けます。インポートしないためモックは不要です。型エイリアスは適用しません。

Guidedog が Python の動作を判断する仕組み

名前は Python の束縛規則に従って解決します。パッケージの __init__.py にある from .app import Flask により、flask.Flask は flask/app.py のクラスを指します。autodoc は :canonical: flask.app.Flask を表示します。基底クラスも同様に解決し、Python と同じ規則でメソッド解決順序を計算します。継承したメンバーは基底クラスのソースから取得します。if TYPE_CHECKING: の中だけでインポートした名前は実行時には存在しないため、それを使う注釈は Sphinx と同じく原文のままです。

docstring は Python が保存する文字列です。エスケープを処理し、Python 3.13 のコンパイラと同じ規則でインデントを取り除きます。属性の説明は Sphinx の解析器と同じ場所から読みます。代入の行末または直前の #: コメントと、代入直後の文字列リテラルです。シグネチャは def から取得します。クラスでは Python の検索順に従い、メタクラスの __call__、__new__、__init__ を調べます。dataclass と NamedTuple ではフィールドを使います。@overload の各定義は実装のシグネチャに優先します。

Python を実行しないと分からないこと

ソースだけでは Python の動作を判断できない場合、Guidedog は対象の名前を示して報告します。文書化できなければ警告を出します。Sphinx より情報が少ない状態で文書化した場合は、-v で表示する注記を出します。

• コンパイル済みのモジュール（.so、.pyd）には読めるソースがないため、オブジェクトを見つけられません。
• コードの実行で得る値（app = Flask(__name__)、now = datetime.now()）には :value: を付けません。計算が必要な既定値はソースの表記を使います。
• ソース検索パスの外にあるデコレータ（@click.command()）が生成する関数は、装飾前の関数として文書化します。
• ソース検索パスの外にあるパッケージのクラスは、インポート元のパスで名前を表示します。そのパスは定義元のモジュールと異なる場合があります。メンバー、コンストラクタのシグネチャ、継承される docstring は分かりません。
• 組み込み型の docstring は分かりません。そのため、独自の docstring がなく dict から継承するはずのメソッドは省きます。
• autodoc のイベント（autodoc-process-docstring、autodoc-skip-member など）を処理する Python 拡張は実行しません。
• 現実のコードを大きく超える深い入れ子は解析せず、autodoc.too_deep を警告します。Python 自体も 200 段の括弧の入れ子を拒否します。Guidedog は数百のオペランドを含む + の連鎖も拒否します。
• 増大し得る処理には上限があります。インポートと別名をたどる名前解決は、1 経路で 48 ステップ、全体で 100,000 ステップまでです。型エイリアスと定数の展開は 10,000 ステップまでで、それを超えると原文を表示します。クラスの MRO は 100 クラスまでたどります。1 つのディレクティブが生成できる数は 10,000 個までで、超過時は autodoc.limit を警告します。この上限に達するのは、自分の名前で自分自身を含むクラスです。

不足するパッケージのソースディレクトリを autodoc_source_paths に追加すれば、これらの制約の多くを解消できます。

再ビルド

autodoc が読んだ Python ファイルはすべて、そのページの依存関係になります。編集すると次のビルドでページを読み直します。オブジェクトが見つからなかったページは毎回読み直すため、ソースに追加されれば次のビルドで検出します。

安全性

文書のビルドでプロジェクトのコードを実行することはありません。Guidedog は Python ソースをテキストとして読み、include と同じ範囲制限を適用します。autodoc_source_paths の下だけを読み、外部に通じるリンクはたどりません。