epydoc - クラウドでオンライン

プログラム：

NAME

epydoc - Python docstring から API ドキュメントを生成する

SYNOPSIS

エピドク [アクション] [オプション] 名前...

DESCRIPTION

エピドク に基づいて、Python モジュールとパッケージの API ドキュメントを生成します。
docstring。 と呼ばれる軽量のマークアップ言語 エピテキスト フォーマットに使用できます
docstrings、およびパラメーターやインスタンスなどの特定のフィールドに関する情報を追加する
変数。 Epydoc は、ReStructuredText、Javadoc、および
平文。 現在、epydoc は、HTML と LaTeX の XNUMX つの基本的な出力形式をサポートしています。

によって作成された HTML API ドキュメント エピドク 以下を含む一連の HTML ファイルで構成されます。
各クラスとモジュールの API ドキュメント ページ。 構文が強調表示されたソース コード ページ
モジュールごとに; 識別子のインデックス ページ。 ヘルプページ; およびフレームベースのテーブル
コンテンツ。 適切な場合、 エピドク 定義されたバグのインデックスページも生成します
用語、および To Do アイテム。 クラス階層ページ; およびパッケージ階層ページ。

によって作成された LaTeX API ドキュメント エピドク メインの LaTeX ファイルと LaTeX
各モジュールのファイル。 使用する場合 --dvi, --psまたは --pdf , その後 エピドク 外部を呼び出します
LaTeX 出力を要求された形式に変換するコマンド。 LaTeX ファイルに注意してください。
個々のモジュールのドキュメントを含む、章または章として含めることができます
LaTeX を使用して、他の LaTeX ドキュメントのセクション \含む 指図。 ご希望の方は
個々のクラスを他の LaTeX ドキュメントに含めてから、 --個別のクラス
クラスごとに個別の LaTeX ファイルを生成するオプション。

エピドク API ドキュメントの完全性を確認するためにも使用できます。 デフォルトでは、
すべての公開パッケージ、モジュール、クラス、メソッド、および関数に docstring があることを確認します
説明。 の --テスト オプションを使用して、実行する追加のテストを指定できます。

再現可能 BUILD 動作

Epydoc で生成されたドキュメント内で現在の日付を使用すると、ドキュメントは次のようになります。
「再現不可能」です。つまり、ファイルの内容がビルドごとに変わることを意味します
ソースツリーがそうでなくても。 再現可能なビルドを生成しやすくするために、これは
バージョンの Epydoc は XNUMX つの機能をサポートしています。 --no-include-build-time オプションと
SOURCE_DATE_EPOCH 環境変数。

この --no-include-build-time オプションは、必要がないことが事前にわかっている場合に使用できます
生成されたドキュメントにタイムスタンプを作成します。 の SOURCE_DATE_EPOCH 環境
変数は、Debian ビルド プロセスなどのパッケージ システムで使用するためのものです。
包装システムが設定されます SOURCE_DATE_EPOCH どういうわけか賢明なタイムスタンプに
ソースツリーの状態に関連し、そのタイムスタンプはむしろ Eypdoc によって使用されます。
現在のタイムスタンプよりも。 を使用してビルドします SOURCE_DATE_EPOCH したがって、再現可能になります。

OPTIONS

Epydoc のオプションは、基本オプション、アクション、生成の XNUMX つのカテゴリに分類されます
オプション、出力オプション、グラフ オプション、および戻り値オプション。

BASIC OPTIONS

名...
文書化する必要があるオブジェクトのリスト。 を使用してオブジェクトを指定できます。
Python のドット付きの名前 ( OSパス)、ファイル名(例: epydoc/epytext.py),
またはディレクトリ名 ( エピドック/）。 ディレクトリ名はパッケージを指定し、
すべてのサブモジュールとサブパッケージを含むように拡張されています。 ご希望の方は
特定のサブモジュールまたはサブパッケージを除外するには、 -除外する オプション
（以下で説明します）。

--config file
追加を指定する構成ファイル オプションおよび名。 このオプション
繰り返される可能性があります。

--q、 - 静かな、 --v、 -詳細
かなりの (または冗長な) 出力を生成します。 複数回使用する場合、このオプション
より静かな（または冗長な）出力を連続的に生成します。

- デバッグ
内部エラーの完全なトレースバックを表示します。

-- 単項
プログレス バーを表示するときに、色やカーソル コントロールを使用しないでください。
警告、またはエラー。

ACTIONS

--html HTML出力を記述します。 [ディフォルト]

- ラテックス LaTeX 出力を書き込みます。

--dvi DVI 出力を書き込みます。

--ps Postscript 出力を書き込みます。

--pdf Adobe Acrobat (pdf) 出力を書き込みます。

- チェック ドキュメントの完全性チェックを実行します。

--ピクルス ドキュメントを pickle ファイルに書き込みます。

GENERATION OPTIONS

--docformat 形式でアーカイブしたプロジェクトを保存します．
のデフォルト値を設定します __docformat__ 〜へ 形式でアーカイブしたプロジェクトを保存します．. __docformat__ モジュールです
モジュール内の docstring のマークアップ言語を指定する変数。
その値は、マークアップ言語の名前で構成され、オプションでその後に
言語コード (など en 英語の場合）。 マークアップ言語のリストについて
現在epydocによって認識されている、実行 エピドク - 助けて ドキュメントフォーマット.

--解析のみ
関連するオブジェクトを解析して、文書化されたオブジェクトに関するすべての情報を収集します。
Python ソースコード; 特に、する 内省を使って集める
文書化されたオブジェクトに関する情報。 このオプションは、次の場合に使用する必要があります。
epydoc は信頼できないコードで実行されます。 またはイントロスペクトできないコードで
依存関係がないため、またはインポートすると望ましくない結果が生じるため
副作用。

-- イントロスペクトのみ
イントロスペクションによって文書化されたオブジェクトに関するすべての情報を収集します。 の
特に、する オブジェクトの Python ソースを解析して情報を収集する
コー​​ド。

-除外する パターン
指定された正規表現に一致する名前を持つオブジェクトを文書化しません
パターン。

--除外-イントロスペクト パターン
その名前を持つオブジェクトに関する情報を収集するためにイントロスペクションを使用しないでください。
指定された正規表現に一致します。

-- 除外解析 パターン
オブジェクトに関する情報を収集するために Python ソース コードの解析を使用しないでください。
その名前は、指定された正規表現と一致します。

- 継承 形式でアーカイブしたプロジェクトを保存します．
継承されたメソッド、変数、および
生成された「サマリー」テーブルのプロパティ。 もしも 形式でアーカイブしたプロジェクトを保存します． が「グループ化」されている場合
継承されたオブジェクトは、それらがどのクラスであるかに基づいてグループにまとめられます
から継承。 もしも 形式でアーカイブしたプロジェクトを保存します． が「リスト」されている場合、継承されたオブジェクトは
要約表の最後にある短いリスト。 もしも 形式でアーカイブしたプロジェクトを保存します． が「含まれる」場合、
継承されたオブジェクトは、継承されていないオブジェクトと混在しています。 デフォルトのフォーマット
HTML 出力は「グループ化」されます。

--show-private、 --プライベートなし
これらのオプションは、プライベート オブジェクトのドキュメントを生成するかどうかを制御します。
デフォルトでは、生成されたドキュメントにはプライベート オブジェクトが含まれており、ユーザーは次のことができます。
「プライベートを表示」をクリックして、プライベートオブジェクトを表示するかどうかを選択します
および「プライベート」リンクを非表示にします。 しかし、ユーザーを直接思いとどまらせたい場合は
プライベート オブジェクトにアクセスする場合は、ドキュメントを生成したくない場合があります
プライベートオブジェクト用。

--show-imports、 --インポートなし
これらのオプションは、生成されたファイルにモジュールのインポートを含めるかどうかを制御します
ドキュメンテーション。 デフォルトでは、インポートは含まれません。

--show-ソースコード, --ソースコードなし
これらのオプションは、epydoc が構文強調表示を生成するかどうかを制御します
HTML 出力の各モジュールのソース コードを含むページ。 デフォルトでは、
ソースコード ページが生成されます。

--include-log
HTML ページを生成する epydoc-log.html すべてのエラーおよび警告メッセージを含む
epydoc によって生成され、生成された出力に含めます。

--no-include-build-time
ページ フッターにビルド時間を出力しないでください。 これは、次の場合に役立ちます。
再現可能なビルドを生成しようとしています。各ビルドは特定の
ソース ツリーのバージョンはまったく同じアーティファクトを生成します。

出力 OPTIONS

-o DIR, - 出力 DIR
出力ディレクトリ。 もしも DIR 存在しない場合は作成されます。 いいえ
出力ディレクトリが指定され、次にアクション名が指定されます (例: HTML or PDFファイル). HTML

-c シート, --css シート
HTML 出力ファイルの CSS スタイルシート。 もしも シート はファイル、次にスタイルシート
そのファイルからコピーされます。 それ以外は、 シート の名前であると見なされます
組み込みのスタイルシート。 組み込みのスタイルシートのリストについては、次を実行してください。 エピドク - 助けて
CSS. CSS スタイルシートが指定されていない場合、デフォルトのスタイルシートは
中古。

-n 名, - 名前 名
ドキュメントが生成されるプロジェクトの名前。

-u URL, --url URL
プロジェクトのホームページの URL。

--ナビリンク HTML
HTML ナビゲーション バーのホームページ リンクの HTML コード。 このHTMLコードなら
ハイパーリンクを含む (<a href=...>)、その後、逐語的に挿入されます。 もしも
ハイパーリンクは含まれておらず、プロジェクトの URL が指定されています (
--url)、指定した URL へのハイパーリンクがリンクに追加されます。

--ヘルプファイル file
代替ヘルプ ファイル。 file HTML ファイルの本文を含める必要があります --
ナビゲーション バーが追加されます。

--show-frames、 --フレームなし
これらのオプションは、HMTL 出力にフレームベースのテーブルを含めるかどうかを制御します。
目次ページです。 デフォルトでは、フレームベースの目次が含まれています。

--個別のクラス
LaTeX 出力で、各クラスを別のセクションに記述します。
ドキュメントにそれらを含める代わりに、ドキュメント
モジュール。 これにより、クラスごとに個別の LaTeX ファイルが作成されるため、
XNUMX つまたは XNUMX つのクラスのドキュメントを
独自の LaTeX ドキュメントのセクション。

グラフ OPTIONS

- グラフ グラフタイプ
タイプのグラフを含める グラフタイプ 生成された出力で。 グラフが生成される
Graphviz dot 実行可能ファイルを使用します。 この実行可能ファイルがパス上にない場合、
つかいます --ドットパス その場所を指定します。 このオプションは、含めるために繰り返すことができます
出力に複数のグラフ タイプ。 グラフタイプ 次のいずれかである必要があります。 を,
クラスツリー, コールグラフまたは UMLクラスツリー.

--ドットパス path
Graphvizへの道 ドット 実行可能ファイル。

--グラフフォント フォント
Graphviz グラフの生成に使用されるフォントの名前。 (例: ヘルベチカまたは
時間）。

--グラフのフォントサイズ サイズ
Graphviz グラフの生成に使用されるフォントのサイズ (ポイント単位)。

--pstat file
コール グラフの生成に使用される pstat 出力ファイル。

リターン VALUE OPTIONS

--エラー時のフェイル
エラーが発生した場合は、失敗を示すゼロ以外の終了ステータスを返します。
遭遇した。

--フェイルオン警告
エラーまたは警告がある場合は、失敗を示すゼロ以外の終了ステータスを返します
(docstring の警告は含まれません)。

--fail-on-docstring-warning
エラーまたは警告がある場合は、失敗を示すゼロ以外の終了ステータスを返します
(docstring 警告を含む) が発生します。

HTML ファイル

によって作成された HTML API ドキュメント エピドク は次のファイルで構成されます。

目的 マニュアル PAGES

index.html
ドキュメントの標準のエントリ ポイント。 通常は、 index.html コピーです
フレームファイルの (フレーム.html）。 しかし、 --フレームなし オプションが使用されている場合、
index.html API ドキュメントのホームページのコピーで、通常は
最上位のパッケージまたはモジュールのドキュメント ページ (またはツリー ページ
トップレベルのパッケージやモジュールはありません)。

モジュール-モジュール.html
モジュールの API ドキュメント。 モジュール の完全なドット名です。
モジュールなど SYS or epydoc.epytext.

class-class.html
クラス、例外、または型の API ドキュメント。 class 完全です
クラスのドット名。例: epydoc.epytext.トークン or 配列.ArrayType.

モジュール-pysrc.html
の Python ソース コードを含む構文が強調表示されたページ モジュール。 この
ページには、API ドキュメント ページに戻るリンクが含まれています。

モジュールツリー.html
モジュール階層。

クラスツリー.html
クラス階層。 このページは、少なくとも XNUMX つのクラスが
文書化されています。

指標

識別子-index.html
文書化されたすべての識別子のインデックス。 識別子インデックスにさらに含まれている場合
3,000 エントリを超えると、文字ごとに別のページに分割されます。
命名 識別子インデックス a.html, 識別子-インデックス-b.html, etc.

用語インデックス.html
明示的にマークされたすべての定義用語の索引。 このページはあくまで
フォーマットされた docstring で少なくとも XNUMX つの定義用語がマークされている場合に生成されます。

バグ-index.html
明示的にマークされたすべてのインデックス @バグ 田畑。 このページは、次の場合にのみ生成されます
少なくても一つ @バグ フィールドは、フォーマットされた docstring にリストされます。

todo-index.html
明示的にマークされたすべてのインデックス @todo 田畑。 このページは、次の場合にのみ生成されます
少なくても一つ @todo フィールドは、フォーマットされた docstring にリストされます。

変更された-index.html
明示的にマークされたすべてのインデックス @かわった 田畑。 このページは生成のみです
少なくとも XNUMX つあれば @かわった フィールドは、フォーマットされた docstring にリストされます。

非推奨のインデックス.html
明示的にマークされたすべてのインデックス @非推奨 田畑。 このページはあくまで
少なくとも XNUMX つの場合に生成されます @非推奨 フィールドは、フォーマットされた docstring にリストされます。

以来-index.html
明示的にマークされたすべてのインデックス @以来 田畑。 このページは生成のみです
少なくとも XNUMX つあれば @以来 フィールドは、フォーマットされた docstring にリストされます。

フレームベース 表 OF 目次

フレーム.html
メインフレームファイル。 ウィンドウの左側にある XNUMX つのフレームには、
目次、およびウィンドウの右側のメイン フレームには
API ドキュメント ページ。

toc.html
最上位の目次ページ。 このページは左上に表示されます
のフレーム フレーム.html、およびへのリンクを提供します toc-everything.html と
トック-モジュール-モジュール.html ページ

toc-everything.html
プロジェクト全体の目次。 このページは
の左下フレーム フレーム.html、およびすべてのクラス、タイプ、
プロジェクトによって定義された例外、関数、および変数。

トック-モジュール-モジュール.html
モジュールの目次。 このページは左下に表示されます
のフレーム フレーム.html、およびすべてのクラス、タイプ、例外へのリンクを提供します。
関数、およびモジュールによって定義された変数。 モジュール 完全な点線です
などのモジュールの名前 SYS or epydoc.epytext.

その他 PAGES

ヘルプ.html
プロジェクトのヘルプ ページ。 このページでは、
epydoc によって作成された Web ページ。

リダイレクト.html
このページでは、JavaScript を使用してドット付きの名前を対応する名前に変換しています
URL。 たとえば、epydoc のドキュメントでは、ページの読み込み
自動的にリダイレクトします
ブラウザから .

epydoc.css
すべての HTML ページを表示するために使用される CSS スタイルシート。

epydoc.js
epydoc で使用される JavaScript 関数を定義するために使用される JavaScript ファイル。

epydoc-log.html
によって生成されたすべての警告とエラーのログを含むページ
epydoc、および使用されたすべてのオプションをリストした表。

ラテックス ファイル

によって作成された LaTeX API ドキュメント エピドク は次のファイルで構成されます。

API.pdf
完全な API ドキュメントを含む Adob​​e Acrobat (pdf) ファイル。 これ
ファイルは、使用する場合にのみ生成されます --pdf オプションを選択します。

アピテックス
トップレベルの LaTeX ファイル。 このファイルは、他の LaTeX ファイルをインポートして、
単一の統一されたドキュメント。

api.dvi
完全な API ドキュメントを含む dvi ファイル。 このファイルは
を使用すると生成されます --dvi オプション、 --ps オプション、または --pdf オプションを選択します。

api.ps 完全な API ドキュメントを含むポストスクリプト ファイル。 このファイルは
を使用すると生成されます --ps オプションまたは --pdf オプションを選択します。

モジュール-モジュール.tex
モジュールの API ドキュメント。 モジュール の完全なドット名です。
モジュールなど SYS or epydoc.epytext.

class-class.tex
クラス、例外、または型の API ドキュメント。 class 完全です
クラスのドット名。例: epydoc.epytext.トークン またはarray.ArrayType。
これらのクラス ドキュメント ファイルは、 --個別のクラス
オプションが使用されます。 それ以外の場合、各クラスのドキュメントはその
モジュールのドキュメント ファイル。

診断

エピテキスト マークアップ 警告 メッセージ
エピテキスト エラーは、無効なマークアップを含むエピテキスト docstring によって発生します。 いつでも
epytext エラーが検出された場合、問題の docstring は平文として扱われます
docstring。 Epydoc は、次の epytext エラーを生成する可能性があります。

悪い ターゲット。
インラインリンク構築に指定されたターゲット (L{...}) 調子が悪いです-
形成されました。 リンクターゲットは有効な Python 識別子である必要があります。

悪い URI ターゲット。
インライン URI 構築に指定されたターゲット (う{...}) は整形式ではありません。
これは通常、インライン マークアップが URI ターゲット内にネストされている場合に発生します。

フィールズ しなければなりません be at 　 top レベル。
フィールドのリスト (@私のお金、など) は他のブロック構造に含まれています
(リストやセクションなど)。

フィールズ しなければなりません be 　 ファイナル 要素。
フィールドのリスト (@私のお金、など) が docstring の末尾にありません。

見出し しなければなりません 発生する at top レベル。
見出しは他のブロック構造 (リストなど) に含まれます。

不適切 ドクターテスト コロナ新型ウィルス(COVID-XNUMX)やメンタルヘルスの崩壊を避ける為の インデント。
doctest ブロックは、最初のプロンプト行のインデントを超えてデデントされます。

不適切 見出し インデント。
セクションの見出しがセクション内の段落と左揃えになっていません。
それを含むセクション。

不適切 段落 インデント。
ブロック内の段落は左揃えではありません。 このエラーはよくあることですが、
プレーンテキストの docstring が epytext を使用して解析されるときに生成されます。

「無効」 逃れる。
未知のエスケープ シーケンスがインライン エスケープ構造で使用されました
(E{...}).

リスト しなければなりません be 凹んだ。
段落の直後のインデントされていない行は、箇条書きで始まります。
Epydoc には、新しいリスト項目を開始するつもりだったのか、それともリスト項目を開始するつもりだったのかがわかりません。
箇条書きのような単語を含める段落。 意図した場合は、
前者、次にリストをインデントします。 後者を意図している場合は、
段落のワードラップ、または単語の最初の文字をエスケープします。
弾丸のように見える。

不安定な 「{」。
docstring にはバランスの取れていない中括弧が含まれています。 Epytext ではすべて中かっこが必要です
バランスがとれていなければなりません。 単一の不均衡な中括弧を含めるには、エスケープを使用します。
シーケンス E{lb} (左中括弧) と E{rb} (右中括弧)。

不安定な 「}」。
docstring にはバランスの取れていない中括弧が含まれています。 Epytext ではすべて中かっこが必要です
バランスがとれていなければなりません。 単一の不均衡な中括弧を含めるには、エスケープを使用します。
シーケンス E{lb} (左中括弧) と E{rb} (右中括弧)。

不明 インライン マークアップ タグ。
不明なタグがインライン マークアップ構造で使用されました ( x{...} ).

間違った 下線 文字 for 見出し。
このセクションの見出しに使用されている下線文字は、
適切なセクションレベル。 下線には「=」文字を使用する必要があります
セクション。 サブセクションの場合は「-」。 サブサブセクションには「~」を使用します。

可能 フォーマットが正しくありません フィールド 項目。
Epytext はフィールド項目のように見える行を検出しましたが、正しくありません
フォーマット済み。 これは通常、末尾のコロン (「:」) が含まれていない場合に発生します。
フィールドタグ内。

可能 見出し 打ち間違え。
Epytext は見出しのように見える XNUMX 行の行を検出しましたが、その数は
下線文字が見出しの文字数と一致しません。
これら XNUMX 行の文字数が正確に一致している必要があります。
見出しとみなされます。

フィールド 警告
フィールド警告は、無効なフィールドを含む docstring によって発生します。 の内容
通常、無効なフィールドは無視されます。 Epydoc は次のフィールドを生成できます
警告：

@私のお金 for 未知の パラメーター パラメータ.
@param フィールドは、そうでないパラメータのタイプを指定するために使用されました。
関数のシグネチャに含まれています。 これは通常、次のタイプミスが原因で発生します。
パラメータ名。

タグ した 期待する an 引数。
フィールドタグ タグ 引数とともに使用されましたが、引数は必要ありません。

タグ 予想される an 引数。
フィールドタグ タグ 引数なしで使用されましたが、引数が必要です。

@タイプ for 未知の パラメーター パラメータ.
@type フィールドを使用して、含まれていないパラメータのタイプを指定しました
関数のシグネチャ内。 これは通常、次のタイプミスが原因で発生します。
パラメータ名。

@タイプ for 未知の 変数 VAR.
@type フィールドは変数の型を指定するために使用されましたが、他のフィールドは使用されませんでした
変数に関する情報はわかっています。 これは通常、次のタイプミスが原因で発生します。
変数名。

不明 フィールド タグ タグ.
docstring に不明なタグを持つフィールドが含まれています タグ.

再定義 of フィールド.
複数のフィールドタグは、次の値を定義します。 フィールド 同じドキュメント文字列内ですが、 フィールド
単一の値のみを取ることができます。

例

エピドク -n エピドク -u http://epydoc.sf.net エピドック/
epydoc パッケージとそのすべての HTML API ドキュメントを生成します。
サブモジュールに出力を書き込みます HTML ディレクトリ。 ヘッダーと
フッター、使用 エピドク プロジェクト名として、および http://epydoc.sf.net プロジェクトとして
URL。

エピドク --pdf -n エピドク エピドック/
epydoc パッケージとそのすべての LaTeX API ドキュメントを生成します。
サブモジュールに出力を書き込みます ラテックス ディレクトリにあります。

EXIT ステータス

0 プログラムの実行が成功しました。

1 使用法エラー。

2 Epydoc がエラーまたは警告を生成し、オプションの XNUMX つを生成しました --エラー時のフェイル,
--フェイルオン警告, or --fail-on-docstring-warning 指定されました。

他の 内部エラー (Python 例外)。

onworks.net サービスを使用して epydoc オンラインを使用する