make_sphinx_files プログラム仕様
Sphinxドキュメント生成プロセスを自動化するスクリプト。
このスクリプトは、PythonスクリプトのDocstring追加、プログラム説明生成、 SphinxドキュメントのためのreStructuredText (RST) ファイルやMarkdownファイルの 作成など、一連のドキュメント生成ルーチンを一括で実行します。
対象のPythonスクリプトに対し、AIによるDocstringの挿入、実行ログの取得、 ダウンロードリンク付きのソースコード表示、APIリファレンス、および コード品質評価のドキュメントを自動生成し、Sphinxプロジェクトの ディレクトリ構造に適合させます。
- ai.make_sphinx_files.check_updated(file1, file2)
2つのファイルの更新日時を比較し、一方のファイルが他方より新しいかどうかを判定します。
この関数は、file1 が存在しない場合は False を返します。 file2 が存在しない場合は、file1 が新しいとみなし True を返します。 両方存在する場合は、file1 の最終更新日時が file2 のそれ以上である場合に True を返します。
- ai.make_sphinx_files.initialize()
コマンドライン引数をパースするための ArgumentParser を初期化します。
スクリプトの目的と、infile、subdir、prompt_explain、 prompt_quality、prompt_add_docstring、api、model、 reasoning_effort、update_index、update、overwrite、 pause といった引数を定義します。 各引数には説明とデフォルト値が設定されています。
- 戻り値:
設定された ArgumentParser オブジェクト。
- 戻り値の型:
- ai.make_sphinx_files.main(args)
Sphinxドキュメント生成の主要な処理フローを実行します。
この関数は、__init__.py の作成、index.template の更新、 各種 .rst および .md ファイルの生成、Docstring追加ツールの実行、 コード品質評価ツールの実行、および生成されたDocstring付きファイルの 適用を行います。入力ファイル、サブディレクトリ、プロンプトファイル、 API設定などのコマンドライン引数に基づいて動作を制御します。
- パラメータ:
args (argparse.Namespace) -- コマンドライン引数をパースした argparse.Namespace オブジェクト。
- 戻り値:
None
- ai.make_sphinx_files.make_api_rst(api_rst, base_name, package_path)
スクリプトのAPIドキュメントを生成するための .rst ファイルを作成します。
このファイルは、Sphinxの automodule ディレクティブを利用して、 指定されたパッケージパスから関数、クラス、メソッドなどを自動的に抽出し、 APIリファレンスを生成します。これにより、コードの構造と公開インターフェースが ドキュメント化されます。
- ai.make_sphinx_files.make_download_rst(download_rst, base_name, script_rel_path)
スクリプトのダウンロードとソースコード表示のための .rst ファイルを作成します。
このファイルは、:download: ロールを使用してスクリプトファイルへのダウンロードリンクを提供し、 .. literalinclude:: ディレクティブを使用して、ユーザーがドキュメント内で ソースコードを直接確認できるようにします。これにより、コードの配布と閲覧が容易になります。
- ai.make_sphinx_files.make_examples_md(examples_md, infile, base_name)
スクリプトの実行例を示すMarkdownファイルを作成します。
この関数は、対象スクリプトの --help 出力を取得し、 現在のディレクトリ内でスクリプト名で始まる関連する画像ファイル (.png, .jpg, .jpeg) やデータファイル (.csv, .xlsx, .xls, .txt) を検索します。 それらの情報をMarkdown形式で整形し、実行例のテンプレートファイルを生成します。
- ai.make_sphinx_files.make_index_rst(index_rst, base_name, package_path)
特定のPythonスクリプトに対する _index.rst ファイルを作成します。
このファイルは、スクリプトのドキュメントのトップレベルインデックスとして機能し、 _download, _usage, _quality, _examples, _api などの 主要なセクションへのリンクを toctree ディレクティブで設定します。
- ai.make_sphinx_files.make_index_template(path, module_path)
プロジェクト全体のメイン index.template ファイルを作成または更新します。
index.template が存在しない場合は新規作成し、toctree ディレクティブに 新しいモジュールのインデックスファイルを追加します。 既に存在する場合は、新しいモジュールパスを追記します。 これにより、Sphinxのメインドキュメントから各モジュールへのリンクが設定されます。
- ai.make_sphinx_files.make_init_py(path)
指定されたパスに空の __init__.py ファイルを作成します。
既にファイルが存在する場合は作成せずにメッセージを表示します。 Pythonパッケージとして認識させるために使用されます。
- パラメータ:
path (str) -- 作成する __init__.py ファイルのパス。
- 戻り値:
None
- ai.make_sphinx_files.read_args(parser)
ArgumentParser から引数を読み込み、必要な追加処理を行います。
reasoning_effort が lmstudio 以外のAPIと組み合わせて指定された場合に エラーを発生させます。また、subdir が指定されていない場合は relative_from_source を呼び出して自動的に設定します。
- パラメータ:
parser (argparse.ArgumentParser) -- 設定済みの ArgumentParser オブジェクト。
- 戻り値:
パースされ、処理された argparse.Namespace オブジェクト。
- 戻り値の型:
- 例外:
SystemExit -- reasoning_effort と api の組み合わせが無効な場合。
- ai.make_sphinx_files.relative_from_source(argv0: str) str
指定されたパスから 'source' ディレクトリ以降の相対パスの親ディレクトリ名を抽出します。
argv0 が path/to/source/subdir/file.py のような形式の場合、 subdir を返します。'source' がパスに含まれない場合は空文字列を返します。 これはSphinxのドキュメント構造におけるサブディレクトリの解決に使用されます。
- パラメータ:
argv0 -- プログラムの実行パス (sys.argv[0] など)。
- 戻り値:
'source' ディレクトリからの相対パスの親ディレクトリ名。'source'が見つからない場合は空文字列。
- 戻り値の型: