make_sphinx_files プログラム仕様

Sphinxドキュメント生成プロセスを自動化するスクリプト。

このスクリプトは、PythonスクリプトのDocstring追加、プログラム説明生成、 SphinxドキュメントのためのreStructuredText (RST) ファイルやMarkdownファイルの 作成など、一連のドキュメント生成ルーチンを一括で実行します。

対象のPythonスクリプトに対し、AIによるDocstringの挿入、実行ログの取得、 ダウンロードリンク付きのソースコード表示、APIリファレンス、および コード品質評価のドキュメントを自動生成し、Sphinxプロジェクトの ディレクトリ構造に適合させます。

make_sphinx_files.py ドキュメント

ai.make_sphinx_files.check_updated(file1, file2)

2つのファイルの更新日時を比較し、一方のファイルが他方より新しいかどうかを判定します。

この関数は、file1 が存在しない場合は False を返します。 file2 が存在しない場合は、file1 が新しいとみなし True を返します。 両方存在する場合は、file1 の最終更新日時が file2 のそれ以上である場合に True を返します。

パラメータ:
  • file1 (str) -- 比較対象の最初のファイルパス。

  • file2 (str) -- 比較対象の2番目のファイルパス。

戻り値:

file1 が file2 より新しい、または file2 が存在しない場合は True、それ以外は False。

戻り値の型:

bool

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 オブジェクト。

戻り値の型:

argparse.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リファレンスを生成します。これにより、コードの構造と公開インターフェースが ドキュメント化されます。

パラメータ:
  • api_rst (str) -- 作成するAPI .rst ファイルのパス。

  • base_name (str) -- スクリプトのベース名(拡張子なし)。

  • package_path (str) -- スクリプトの完全なパッケージパス(例: subdir.modulename)。

戻り値:

None

ai.make_sphinx_files.make_download_rst(download_rst, base_name, script_rel_path)

スクリプトのダウンロードとソースコード表示のための .rst ファイルを作成します。

このファイルは、:download: ロールを使用してスクリプトファイルへのダウンロードリンクを提供し、 .. literalinclude:: ディレクティブを使用して、ユーザーがドキュメント内で ソースコードを直接確認できるようにします。これにより、コードの配布と閲覧が容易になります。

パラメータ:
  • download_rst (str) -- 作成するダウンロード .rst ファイルのパス。

  • base_name (str) -- スクリプトのベース名(拡張子なし)。

  • script_rel_path (str) -- ソースディレクトリからのスクリプトの相対パス。

戻り値:

None

ai.make_sphinx_files.make_examples_md(examples_md, infile, base_name)

スクリプトの実行例を示すMarkdownファイルを作成します。

この関数は、対象スクリプトの --help 出力を取得し、 現在のディレクトリ内でスクリプト名で始まる関連する画像ファイル (.png, .jpg, .jpeg) やデータファイル (.csv, .xlsx, .xls, .txt) を検索します。 それらの情報をMarkdown形式で整形し、実行例のテンプレートファイルを生成します。

パラメータ:
  • examples_md (str) -- 作成する実行例Markdownファイルのパス。

  • infile (str) -- 対象となるPythonスクリプトファイル。

  • base_name (str) -- スクリプトのベース名(拡張子なし)。

戻り値:

None

ai.make_sphinx_files.make_index_rst(index_rst, base_name, package_path)

特定のPythonスクリプトに対する _index.rst ファイルを作成します。

このファイルは、スクリプトのドキュメントのトップレベルインデックスとして機能し、 _download, _usage, _quality, _examples, _api などの 主要なセクションへのリンクを toctree ディレクティブで設定します。

パラメータ:
  • index_rst (str) -- 作成する _index.rst ファイルのパス。

  • base_name (str) -- スクリプトのベース名(拡張子なし)。

  • package_path (str) -- スクリプトの完全なパッケージパス(例: subdir.modulename)。

戻り値:

None

ai.make_sphinx_files.make_index_template(path, module_path)

プロジェクト全体のメイン index.template ファイルを作成または更新します。

index.template が存在しない場合は新規作成し、toctree ディレクティブに 新しいモジュールのインデックスファイルを追加します。 既に存在する場合は、新しいモジュールパスを追記します。 これにより、Sphinxのメインドキュメントから各モジュールへのリンクが設定されます。

パラメータ:
  • path (str) -- index.template ファイルのパス。

  • module_path (str) -- Sphinxドキュメントツリーに追加するモジュールのパス(例: subdir/modulename)。

戻り値:

None

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 オブジェクト。

戻り値の型:

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'が見つからない場合は空文字列。

戻り値の型:

str

ai.make_sphinx_files.run_step(message, cmd_list)

指定されたコマンドリストを実行し、その結果を表示します。

外部コマンドの実行状況をユーザーに通知し、エラーが発生した場合は それを報告します。コマンドの標準出力と標準エラー出力は表示されませんが、 返却コードがゼロでない場合はエラーとみなします。

パラメータ:
  • message -- 実行するステップを説明するメッセージ。

  • cmd_list -- 実行するコマンドとその引数のリスト。

戻り値:

コマンドが正常に実行された場合はTrue、エラーが発生した場合はFalse。

戻り値の型:

bool