sphinx.ext.viewcode – ハイライトされたソースコードへのリンクを追加¶
モジュール作者: Georg Brandl
バージョン 1.0 で追加.
この拡張機能は、Python オブジェクトの記述 (.. class::、.. function:: など) を調べ、オブジェクトが含まれているソースファイルを見つけようとします。見つかった場合、各モジュールに対して、ハイライトされたソースコードのバージョンを含む個別の HTML ページが出力され、記述されたオブジェクトのソースコードに移動するリンクが、すべてのオブジェクトの説明に追加されます。ソースから説明へのリンクも挿入されます。
警告
基本的に、viewcode 拡張機能は、リンク先のモジュールをインポートします。モジュールにインポート時に副作用がある場合、sphinx-build の実行時にこれらが実行されます。
(ライブラリモジュールとは対照的に) スクリプトをドキュメント化する場合は、メインルーチンが if __name__ == '__main__' 条件で保護されていることを確認してください。
さらに、viewcode でモジュールをインポートしたくない場合は、viewcode-find-source イベントを使用して、ソースコードの場所を viewcode に伝えることができます。
viewcode_follow_imported_members が有効になっている場合、viewcode-follow-imported イベントを使用してインポートされた属性を解決する必要もあります。
この拡張機能は、html、applehelp、devhelp、htmlhelp、qthelp などの HTML 関連のビルダーでのみ機能し、singlehtml を除きます。デフォルトでは、epub ビルダーはこの拡張機能をサポートしていません ( viewcode_enable_epub を参照)。
設定¶
- viewcode_follow_imported_members¶
これが
Trueの場合、viewcode 拡張機能は、他の拡張機能によってモジュールの名前を解決するためにviewcode-follow-importedイベントを発行します。デフォルトはTrueです。バージョン 1.3 で追加.
バージョン 1.8 で変更:
viewcode_importからviewcode_follow_imported_membersに名前が変更されました。
- viewcode_enable_epub¶
これが
Trueの場合、epub ビルダーを使用する場合でも viewcode 拡張機能が有効になります。この拡張機能は toctree の外部にページを生成しますが、これは epub 形式としては推奨されません。1.4.x までは、この拡張機能は常に有効でした。1.4.x と同じように epub を生成する場合は、
Trueを設定する必要がありますが、epub 形式チェッカーのスコアは悪化します。デフォルトは
Falseです。バージョン 1.5 で追加.
警告
すべての epub リーダーが viewcode 拡張機能によって生成されたページをサポートしているわけではありません。これらのリーダーは、toctree の下にないページへのリンクを無視します。
一部のリーダーのレンダリング結果が破損し、リーダーがサポートしていても epubcheck のスコアが悪化します。
- viewcode_line_numbers¶
デフォルト:
False。Trueに設定すると、ハイライトされたコードに行番号がインラインで追加されます。バージョン 7.2 で追加.
- viewcode-find-source(app, modname)¶
バージョン 1.8 で追加.
モジュールのソースコードを見つけます。このイベントのイベントハンドラーは、ソースコード自体とタグの辞書をタプルで返す必要があります。辞書は、クラス、関数、属性などの名前を、その型、開始行番号、終了行番号のタプルにマップします。型は、「class」、「def」、または「other」のいずれかである必要があります。
- パラメーター:
app – Sphinx アプリケーションオブジェクト。
modname – ソースコードを見つけるモジュールの名前。
- viewcode-follow-imported(app, modname, attribute)¶
バージョン 1.8 で追加.
属性の元のモジュールの名前を見つけます。
- パラメーター:
app – Sphinx アプリケーションオブジェクト。
modname – 属性が属するモジュールの名前。
attribute – フォローするメンバーの名前。