Ruffでdocstringのコード例が整形されない？設定と構文の確認方法

Python本体は整形されるのに、docstring内のコード例だけ変わらない場合、最初に確認するのはdocstring-code-formatです。この機能は既定で無効なので、設定を有効にしたうえで、例の形式、Python構文、実行結果を順に切り分けます。

• Ruffの版と実行場所を確認する
• 使用中の設定ファイルへ必要な項目だけ追加する
• 認識されるdocstringコード形式と構文を確認する
• 整形後にdoctestを別途実行する

1. Ruffの版と設定ファイルの場所を確認する

まず、対象プロジェクトのディレクトリで次を実行します。Windowsのコマンドプロンプトではpwdをcdに置き換えます。

ruff --version
pwd

Ruffは対象ファイルに最も近い設定を使い、extendを明示しない限り親子の設定を結合しません。同じ場所に複数ある場合は.ruff.toml、ruff.toml、pyproject.tomlの順で優先されます。実行場所と編集した設定がずれていないかは、Ruff公式の設定ファイル探索で確認できます。既存設定は丸ごと置き換えず、現在使われているファイルへ必要な項目だけ足します。

2. 小さなdoctestで未設定時の差分を見る

説明用に、sample.pyへ次の例を保存します。関数本体とdoctest内の空白を意図的に崩しています。

def add(a,b):
    """2つの数を加算する。

    >>> add( 1,2 )
    3
    """
    return a+b

設定を追加する前に、書き換えず差分だけを表示します。

ruff format --diff sample.py

--diffはファイルへ適用せず、変更候補を表示する確認用です。既定設定では関数定義やreturnが差分になっても、docstring内の>>> add( 1,2 )は残る可能性があります。これは説明用の例です。実際の差分は手元のRuff版と設定で確認してください。変更候補がある場合、確認系の実行は終了ステータスが非0になり得ます。

3. 使用中の設定ファイルへ1項目だけ追加する

公式設定リファレンスでは、docstring-code-formatの既定値はfalseです。次の2つは代替案なので、実際に使っている設定ファイルの行だけを選び、両方へ重複して書かないでください。

pyproject.tomlを使う場合：

[tool.ruff.format]
docstring-code-format = true

ruff.tomlまたは.ruff.tomlを使う場合：

[format]
docstring-code-format = true

すでに同じテーブルがあるなら、新しいテーブルを重ねて作らず、その中へ設定行だけ追加します。

4. 設定後のdiffを確認して適用する

同じ場所から再度diffを取ります。

ruff format --diff sample.py

設定が読み込まれ、例がdoctestとして認識され、構文も有効なら、関数本体に加えて>>> add(1, 2)への整形候補も確認できます。内容を確認したら実ファイルへ適用します。

ruff format sample.py

適用後は、書き換えない--checkで再確認できます。

ruff format --check sample.py

5. 有効にしても変わらない場合は形式と構文を確認する

Ruff公式のdocstring formattingが認識する主な形式は次のとおりです。

• >>>で始まるdoctest形式
• python、py、python3、py3付き、または言語名なしのMarkdownフェンス
• Pythonコードとして扱われるreStructuredTextのliteral block
• 言語名にpython、py、python3、py3を指定したreStructuredTextのcode-blockまたはsourcecodeディレクティブ

対象形式でも、コードが有効なPythonとして解析できない場合や、整形によって無効なPythonになる場合は、その例がそのまま残されます。したがって「変化しなかった」ことは、コードが正しい証拠ではありません。たとえば次は無効な構文です。

>>> add(1,,2)

docstring-code-line-lengthの既定値はdynamicで、周囲のPythonコードの行長設定とdocstringの字下げを考慮します。ただし対象は認識されたコード例であり、一般の説明文を自動で折り返す設定ではありません。

6. 整形と実行確認を分ける

Ruffのformatterは見た目を整える機能で、例の戻り値や意味まで検証しません。今回の>>>形式は、Python公式のdoctestコマンドで別に実行確認します。

python -m doctest sample.py

成功時は通常何も表示されません。試した例を表示したい場合は-vを付けます。整形が通ってもdoctestが失敗することはあり、その逆もあるため、両方を別工程として確認するのが安全です。

よくある質問

diffやcheckが非0で終了するのはエラーですか

変更が必要なファイルを検出したために非0になる場合があります。構文エラーや設定エラーと同じ意味とは限りません。CIでは終了ステータスだけでなく差分表示も確認します。公式の終了コードも参照してください。

docstringの説明文も整形されますか

この設定が対象にするのはdocstring内で認識されたPythonコード例です。通常の説明文全体を折り返す機能ではありません。

ruff checkでも同じ問題を調べられますか

ruff checkはlint、今回扱うruff formatは整形で、目的が異なります。lint側の設定で迷った場合は、関連記事「Ruffで必要なnoqaがRUF100になる原因｜selectとextend-selectの違い」を参照してください。

まとめ

1. ruff --versionと実行場所、実際に読まれる設定ファイルを確認する
2. 小さなdoctestをruff format --diffで比較する
3. 使用中の設定にdocstring-code-format = trueだけを追加する
4. 無変化なら形式と構文を確認し、整形後にdoctestを別実行する