explain_program5.py 技術ドキュメント

プログラムの動作

explain_program5.py は、指定されたプログラムコードを解析し、AI（OpenAIまたはGoogle Gemini）を利用してその技術ドキュメントをMarkdown形式で自動生成するツールです。プログラマーが手動でドキュメントを作成する手間を大幅に削減し、効率的なドキュメント生成を可能にします。

このプログラムの主な機能は以下の通りです。

  • ファイルパターンによる複数ファイル処理: ワイルドカードパターン（例: *.py）を使用して複数のプログラムファイルを一括で処理できます。

  • AI API連携: OpenAI (GPT-4, GPT-5相当) またはGoogle Gemini APIと連携し、プログラムコードから内容を理解してドキュメントを生成します。

  • 柔軟なプロンプト設定: INI形式の設定ファイルを通じて、AIへのプロンプトテンプレート、システムロール、使用するAIモデルなどを細かくカスタマイズできます。これにより、特定の形式や内容のドキュメント生成が可能です。

  • 多様な言語への対応: ファイルの拡張子に基づいてプログラム言語を自動判別し、AIへの指示に含めることができます。

  • ファイル管理機能: 既に生成されたドキュメントファイルの更新日時とソースファイルの更新日時を比較し、最新でない場合にのみ再生成するスキップ機能や、既存ファイルを上書きするオプションを提供します。

本プログラムは、特に大規模なプロジェクトにおいて、多数のスクリプトやモジュールのドキュメントを迅速かつ一貫性のある形式で作成する際に役立ちます。

原理

explain_program5.py は、以下の主要なアルゴリズムとコンポーネントに基づいて動作します。

  1. INIファイル解析:

    • read_ini 関数は、INI形式のファイルから設定を読み込みます。このカスタムパーサーは、キーと値のペア、複数行にわたる値（トリプルクォート """...""" または '''...''' で囲まれた内容）、および $VAR_NAME 形式の変数展開をサポートしています。

    • INIファイルは、AIへのプロンプトテンプレート（例: PROMPT_MAIN, PROMPT_LIB）、システムロール (SYSTEM_ROLE)、AIモデルの設定などのカスタマイズ情報を提供します。

    • 変数展開は、すべてのキーと値が読み込まれた後、re.sub(r"\$(\w+)\b", expand_var, val) を用いて一括で実行されます。これにより、INIファイル内で定義された他の値を参照できます。

  2. ファイル検索とフィルタリング:

    • glob.glob(args.pattern) を使用して、コマンドライン引数で指定されたワイルドカードパターンに一致するすべてのファイルを検索します。

    • 各ファイルについて、出力ファイル（デフォルトでは .md 拡張子）の存在と更新日時を確認します。--update オプションが指定されている場合、出力ファイルが入力ファイルよりも新しい場合は処理をスキップし、不要なAI呼び出しを防ぎます。--overwrite オプションは常に上書きします。

  3. プログラム言語の判別:

    • language_dict に定義された辞書とファイルの拡張子（例: .py, .pl, .cpp）を照合し、プログラムの言語を判別します。これにより、AIへのプロンプトで適切な言語名を指定できます。

    • get_program_type 関数は、ファイル名や拡張子に基づいてプログラムのタイプ（main または lib）を判別し、適切なプロンプトテンプレートの選択に利用します。

  4. プロンプト構築:

    • INIファイルから読み込んだプロンプトテンプレート（例: PROMPT_MAIN）を基に、実際のAIへのプロンプトが構築されます。

    • テンプレート内のプレースホルダー（{{script_name}}, {{code}}, {{lang}}）は、現在の処理対象ファイルのファイル名、コード内容、および判別された言語名にそれぞれ置き換えられます。

    • AIへの命令（instructions または role）として、INIファイルで定義された SYSTEM_ROLE が使用されます。

  5. AI API呼び出し:

    • tkai_lib ライブラリを介して、指定されたAI API（OpenAIまたはGoogle Gemini）を呼び出します。

    • query_openai4, query_openai5, query_google のいずれかの関数が使用され、構築されたプロンプトがAIに送信されます。

    • AIからの応答は、生成されたドキュメントのテキストとして抽出されます。

  6. 結果の保存:

    • AIから取得したドキュメントテキストは、Markdownファイルとして出力パスに保存されます。ファイルエンコーディングはUTF-8を使用します。

本プログラムは直接的な数式や物理式を使用していませんが、上記のアルゴリズムを通じてAIの自然言語処理能力を最大限に活用し、技術ドキュメント生成という課題を解決しています。

必要な非標準ライブラリとインストール方法

本プログラムは、カスタムライブラリである tkai_lib に依存しています。このライブラリは標準Pythonインストールには含まれていません。

  • tkai_lib:

    • インストール方法: プログラムのソースコードを見ると、ImportError ハンドリングがあり、「tkai_lib が見つかりません。パスを確認してください。」というメッセージが出力されます。これは、tkai_lib が別途提供されるか、環境変数 PYTHONPATH などでパスが通されている必要があることを示唆しています。

    • 一般的な pip コマンドでのインストール方法は提供されていません。tkai_lib が site-packages にインストールされているか、またはスクリプトがアクセスできるパスに配置されている必要があります。

    • 依存関係: tkai_lib は内部でOpenAIまたはGoogle GeminiのAPIクライアントライブラリを使用している可能性があります。これらのライブラリ（例: openai, google-generativeai) は、tkai_lib の機能を利用するために別途インストールが必要になる場合があります。tkai_lib のドキュメントを参照し、必要な依存関係をインストールしてください。

必要な入力ファイル

explain_program5.py の実行には、以下の入力ファイルが必要です。

  1. 対象となるプログラムコードファイル:

    • 形式: Python (.py), Perl (.pl, .pm), C (.c), C++ (.cpp), Pascal (.pas), Fortran (.f), Javascript (.js), Java (.java), Go (.go), Bash Script (.sh), HTML (.html) など、language_dict で定義されている任意のプログラム言語のソースコード。あるいは、language_dict にない拡張子の場合は"text"として扱われます。

    • データ構造: 通常のテキストファイル形式で、コードが記述されている必要があります。

    • 指定方法: コマンドライン引数の pattern でワイルドカード形式で指定します（例: *.py, my_script.pl）。

  2. INI設定ファイル:

    • ファイル名: デフォルトでは explain_program5.ini。--inifile オプションで別のパスを指定できます。

    • 形式: INI形式のテキストファイル。

    • データ構造: AIへのプロンプトテンプレート、システムロール、その他の設定を記述します。

      • PROMPT_MAIN: メインプログラム用のプロンプトテンプレート。{{script_name}} (スクリプト名), {{code}} (コード本体), {{lang}} (言語名) のプレースホルダーが使用されます。

      • PROMPT_LIB: ライブラリ/モジュール用のプロンプトテンプレート。

      • SYSTEM_ROLE: AIへのシステム指示（アシスタントの役割定義）。

      • 複数行の値は """ または ''' で囲んで記述できます。

      • $VAR_NAME 形式でINIファイル内の他の設定値を参照し、展開できます。

    • 例 (explain_program5.ini):

      # AIに渡すプロンプトのテンプレート
PROMPT_MAIN = """# {{script_name}} 技術ドキュメント

概要

この{{lang}}スクリプト{{script_name}}の目的と主な機能について説明してください。

プログラムの動作

スクリプトの各セクションまたは主要な関数が何をするのか、順を追って説明してください。

原理

使用されている主要なアルゴリズム、データ構造、または概念について解説してください。

使用方法

コマンドラインでの基本的な実行方法と引数を説明してください。

コード

上記構成に従い、詳細な技術ドキュメントを作成してください。"""

    # AIの役割を定義
    SYSTEM_ROLE = "あなたは、提供されたプログラムコードを分析し、その技術ドキュメントをMarkdown形式で専門的かつ詳細に作成するAIアシスタントです。"

    # 必要に応じて追加の設定
    DEFAULT_MODEL = "gemini-pro"
    ```

  1. AI設定ファイル (ai.env):

    • ファイル名: ai.env (固定)。

    • 形式: 環境変数を設定するプレーンテキストファイル。

    • データ構造: AI APIキーや使用するモデル名などを環境変数として定義します。

      • openai_api_key: OpenAI APIのシークレットキー。

      • openai_model: OpenAIで使用するモデル名（例: gpt-4-turbo, gpt-3.5-turbo）。

      • openai_model5: OpenAIで使用するGPT-5相当のモデル名。

      • gemini_api_key: Google Gemini APIのシークレットキー。

      • gemini_model: Google Geminiで使用するモデル名（例: gemini-pro）。

    • 例 (ai.env):

      openai_api_key=sk-YOUR_OPENAI_API_KEY
openai_model=gpt-4-turbo
openai_model5=gpt-4-turbo
gemini_api_key=YOUR_GEMINI_API_KEY
gemini_model=gemini-pro

生成される出力ファイル

explain_program5.py は、以下の種類のファイルを出力します。

  1. Markdownドキュメントファイル (.md):

    • ファイル名:

      • 入力ファイルが単一で output 引数が指定された場合、その output 名になります。

      • output 引数が指定されず、入力ファイルが単一または複数の場合、各入力ファイルのベース名に .md 拡張子が付加されたファイルが生成されます（例: my_script.py -> my_script.md）。

    • 形式: Markdown形式のテキストファイル。

    • 内容: AIが生成したプログラムコードの技術ドキュメント。INIファイルで定義されたプロンプトテンプレートに従い、プログラムの概要、動作、原理、使用方法、コードなどが記述されます。コードブロック（言語指定付き）も含まれます。

コマンドラインでの使用例 (Usage)

explain_program5.py は、コマンドラインから以下の形式で実行します。

python explain_program5.py <pattern> [output] [options]

  • <pattern>: 対象ファイルのワイルドカードまたはファイルパス（例: '*.py', 'my_script.py'）。必須。

  • [output]: 出力ファイル名。単一の入力ファイルを処理する場合にのみ指定可能です。指定しない場合、入力ファイル名から自動生成されます。オプション。

オプション:

  • --inifile INIFILE: プロンプト設定INIファイルのパスを指定します。デフォルトは ./explain_program5.ini です。

  • --api {openai,openai5,google,gemini}: 使用するAI APIを指定します。

    • openai: OpenAI API (GPT-4相当のモデル)。

    • openai5: OpenAI API (GPT-5相当のモデル)。

    • google: Google Gemini API。

    • gemini: Google Gemini API (同上)。

    • デフォルトは google です。

  • -t {main,lib}, --program_type {main,lib}: プログラムのタイプを明示的に指定します。これにより、INIファイル内の PROMPT_MAIN または PROMPT_LIB のいずれを使用するかが決定されます。指定しない場合、ファイルの命名規則に基づいて自動判別されます。

  • -u UPDATE, --update UPDATE: 既存の出力ファイルが入力ファイルよりも新しい場合、処理をスキップするかどうかを指定します。0 で常に処理、1 でスキップ（デフォルト: 0）。

  • -w OVERWRITE, --overwrite OVERWRITE: 既存の出力ファイルを常に上書きするかどうかを指定します。0 でスキップ（更新日時比較）、1 で上書き（デフォルト: 0）。

コマンドラインでの具体的な使用例

ここでは、explain_program5.py 自身をドキュメント化する例を示します。

まず、以下のINI設定ファイル (explain_program5.ini) とAI設定ファイル (ai.env) が存在すると仮定します。

explain_program5.ini の内容:

# AIに渡すプロンプトのテンプレート
PROMPT_MAIN = """# {{script_name}} 技術ドキュメント

## 概要
この{{lang}}スクリプト`{{script_name}}`の目的と主な機能について説明してください。

## プログラムの動作
スクリプトの各セクションまたは主要な関数が何をするのか、順を追って説明してください。

## 原理
使用されている主要なアルゴリズム、データ構造、または概念について解説してください。

## 使用方法
コマンドラインでの基本的な実行方法と引数を説明してください。

## コード
```{{lang}}
{{code}}

上記構成に従い、詳細な技術ドキュメントを作成してください。"""

AIの役割を定義

SYSTEM_ROLE = "あなたは、提供されたプログラムコードを分析し、その技術ドキュメントをMarkdown形式で専門的かつ詳細に作成するAIアシスタントです。"


**`ai.env` の内容 (実際のAPIキーに置き換えてください)**:

openai_api_key=sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX openai_model=gpt-4-turbo gemini_api_key=AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX gemini_model=gemini-pro


上記のファイルが準備できたら、以下のコマンドを実行します。

```bash
python explain_program5.py explain_program5.py --api google --output explain_program5_doc.md --overwrite 1

実行結果の説明:

  1. explain_program5.py スクリプトは、自身 (explain_program5.py) を入力ファイルとして読み込みます。

  2. --api google オプションにより、Google Gemini APIが使用されます。

  3. explain_program5.ini から PROMPT_MAIN と SYSTEM_ROLE が読み込まれ、explain_program5.py のコードとファイル名、言語 (python) を埋め込んだプロンプトが構築されます。

  4. 構築されたプロンプトがGoogle Gemini APIに送信されます。

  5. AIによって生成されたMarkdown形式のドキュメントが、explain_program5_doc.md というファイル名で現在のディレクトリに保存されます。

  6. --overwrite 1 オプションにより、もし explain_program5_doc.md が既に存在しても上書きされます。

explain_program5_doc.md の内容は、explain_program5.py の機能、動作原理、使用方法などが、INIファイルで定義された構成（概要、プログラムの動作、原理、使用方法、コード）に従って記述されたMarkdownテキストになります。例えば、# explain_program5.py 技術ドキュメント というタイトルで始まり、その後にプログラムの詳細な説明が続くでしょう。