make_sphinx_files.py 技術ドキュメント

プログラムの動作

make_sphinx_files.py は、指定されたPythonスクリプトを対象として、Sphinx形式の技術ドキュメント（主にMarkdownとreStructuredTextファイル）の自動生成と更新を支援するツールです。このプログラムは、以下の主要な機能を自動化することで、Pythonプロジェクトのドキュメント作成プロセスを効率化します。

  • Docstringの自動追加: 外部スクリプト add_docstring.py を利用し、指定されたPythonスクリプトに関数やクラスのDocstringを自動的に追加または更新します。

  • プログラム解説の生成: 外部スクリプト explain_program5.py を利用し、プログラムの目的、使用方法（usage）、コード品質評価などのMarkdown形式のドキュメントを生成します。

  • Sphinx用ファイルの生成: Sphinxプロジェクトに必要な __init__.py や、各種 .rst ファイル（APIリファレンス、ダウンロードリンク、モジュールインデックスなど）を自動的に作成します。

  • 実行例の生成: 対象スクリプトの --help 出力や、同一ディレクトリ内の関連する画像ファイル、データファイルを自動的に収集し、実行例 (_examples.md) を作成します。

  • ファイルのバックアップと更新管理: Docstringが追加される前に元のPythonスクリプトのバックアップを作成し、ファイルの更新日時を比較することで不必要なドキュメント生成ステップをスキップします。

このプログラムは、特に大規模なプロジェクトや、頻繁に更新されるコードベースにおいて、ドキュメントの鮮度と整合性を保つための課題を解決します。

原理

make_sphinx_files.py は、以下のアルゴリズムと仕組みに基づいて動作します。

  1. 引数解析: コマンドライン引数パーサー argparse を使用して、入力ファイル、サブディレクトリ、使用するAIモデルのAPI、プロンプトファイルなどの設定を読み込みます。特に、--subdir が指定されない場合、入力ファイルパスから source ディレクトリを検索し、それ以降のパスをサブディレクトリとして自動認識します。

    • relative_from_source(argv0) 関数は、入力ファイルの絶対パスから "source" ディレクトリの位置を特定し、その後のパスを相対パスとして抽出します。これは、Sphinxドキュメントのソース構造に合わせるためのものです。

  2. 初期ファイル生成:

    • __init__.py: Pythonパッケージとして認識させるための空のファイルを作成します。

    • index.template: プロジェクト全体のSphinxドキュメントのメインとなる toctree (.. toctree::) を定義し、生成されるモジュール固有のインデックス ([basename]_index) を含めるように設定します。

    • [basename]_index.rst: 特定のモジュールに関するメインの toctree を定義し、ダウンロード、使用方法、品質、実行例、APIリファレンスへのリンクを構築します。

    • [basename]_download.rst: 対象のPythonスクリプトのダウンロードリンクと、ソースコードをそのまま表示する literalinclude ディレクティブを含むファイルを作成します。

    • [basename]_api.rst: Sphinxの automodule ディレクティブを利用し、対象PythonスクリプトのAPIドキュメントを自動生成するためのファイルを作成します。これにより、コード内のDocstringから関数、クラス、メソッドの情報を抽出して表示できます。

  3. Docstringと解説の生成:

    • 更新チェック: check_updated(file1, file2) 関数を使用し、file1 の更新日時が file2 の更新日時以降であるかを確認します。これにより、入力ファイルが変更されていない場合は、外部スクリプトの実行をスキップし、処理時間を短縮します。

    • 外部スクリプトの実行:

      • add_docstring.py の呼び出し: run_step 関数を通じて add_docstring.py を実行し、入力ファイルにDocstringを追加します。成功した場合、元のファイルをバックアップし、Docstringが追加された一時ファイルで元のファイルを上書きします。

      • explain_program5.py の呼び出し: run_step 関数を通じて explain_program5.py を実行し、プログラムの使用方法 (_usage.md) とコード品質評価 (_quality.md、--prompt_quality 指定時) のMarkdownドキュメントを生成します。これらの外部スクリプトは、AIモデル（OpenAI, Google Geminiなど）と連携してコンテンツを生成することが想定されます。

  4. 実行例の生成 (make_examples_md):

    • 対象Pythonスクリプトの --help オプションを実行し、その出力をキャプチャします。

    • 現在のディレクトリから、入力ファイル名で始まる画像ファイル（.png, .jpg, .jpeg）とデータファイル（.csv, .xlsx, .xls, .txt）を検索します。

    • これらをすべて集約し、[basename]_examples.md としてMarkdown形式で出力します。help出力は <pre> タグで囲まれ、画像ファイルはMarkdownの画像埋め込み構文で表示されます。

  5. プロセス管理:

    • run_step 関数は、subprocess.run を使用して外部コマンドを実行し、その結果（成功/失敗）をユーザーに表示します。

    • traceback モジュールを利用して、予期せぬエラー発生時に詳細なスタックトレースを出力し、デバッグを支援します。

このプログラムは、手作業でのドキュメント作成の労力を削減し、常に最新のコードベースに基づいたドキュメントを提供することを目指しています。

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

make_sphinx_files.py 自体はPythonの標準ライブラリ（os, sys, argparse, shutil, subprocess, traceback, pathlib, datetime）のみを使用しており、追加の非標準ライブラリは直接必要ありません。

しかし、このプログラムは以下の外部Pythonスクリプトに依存しており、これらのスクリプトは非標準ライブラリに依存する可能性があります。特に、AIモデルのAPIを利用するためには、それぞれのライブラリのインストールが必要です。

  • add_docstring.py

  • explain_program5.py

これらの外部スクリプトがOpenAIまたはGoogle GeminiのAPIを使用する場合、対応するライブラリをインストールする必要があります。

OpenAI API を使用する場合

pip install openai

Google Gemini API を使用する場合

pip install google-generativeai

推奨されるインストール方法: 依存する外部スクリプトが使用するAI APIに応じて、上記いずれか、または両方をインストールしてください。 例えば、--api google オプションを使用する場合は google-generativeai が必要となります。

必要な入力ファイル

make_sphinx_files.py は、以下のファイルとディレクトリ構造を期待します。

  1. 対象のPythonスクリプトファイル:

    • プログラムの主要な入力であり、ドキュメントを生成する対象となるPythonファイルです。

    • 例: my_script.py

    • コマンドライン引数で infile として指定します。

  2. プロンプト設定ファイル:

    • explain_program5.py や add_docstring.py などのAIを利用する外部スクリプトがコンテンツを生成する際に使用するプロンプト（指示）が記述されたINI形式のファイルです。

    • explain_program5.ini: プログラムの「使用方法」ドキュメント生成用プロンプト。（デフォルト: explain_program5.ini）

    • prompt_quality.ini: プログラムの「コード品質評価」ドキュメント生成用プロンプト。（デフォルト: prompt_quality.ini）

    • prompt_add_docstring.ini: Docstring追加用プロンプト。（デフォルト: 空、add_docstring.py 内部デフォルトを使用）

    • これらはコマンドライン引数でパスを指定できます。

  3. 既存の関連ファイル（オプション）:

    • 同じディレクトリ内に存在する、対象Pythonスクリプト名で始まる以下のファイルが自動的に検出され、_examples.md に組み込まれます。

      • 画像ファイル: .png, .jpg, .jpeg 拡張子を持つファイル。

      • データファイル: .csv, .xlsx, .xls, .txt 拡張子を持つファイル。

  4. 既存のドキュメントファイル（オプション）:

    • __init__.py, index.template, [basename]_index.rst, [basename]_download.rst, [basename]_api.rst, [basename]_usage.md, [basename]_quality.md, [basename]_examples.md などが既に存在する場合、make_sphinx_files.py は通常、これらのファイルを上書きせずにスキップします（ただし、--overwrite オプションを使用すると上書きされます）。また、入力ファイルの更新日時と比較し、ドキュメントの方が新しい場合は生成をスキップします。

生成される出力ファイル

make_sphinx_files.py は、実行されたディレクトリ（または --subdir で指定されたディレクトリ）に以下のファイルを生成します。

  1. __init__.py:

    • Pythonパッケージとしてディレクトリを認識させるための空ファイル。

  2. index.template:

    • プロジェクト全体のSphinxドキュメントのメインtoctreeファイル。

    • 生成されたモジュール固有の [basename]_index へのリンクを含みます。

  3. [basename]_index.rst:

    • [basename] は入力Pythonスクリプトのファイル名（拡張子なし）。

    • 特定のモジュールのメインtoctreeファイル。

    • [basename]_download.rst, [basename]_usage.md, [basename]_quality.md, [basename]_examples.md, [basename]_api.rst へのリンクを含みます。

  4. [basename]_download.rst:

    • 対象Pythonスクリプトのダウンロードリンクと、そのソースコードをシンタックスハイライト付きで表示するreStructuredTextファイル。

  5. [basename]_usage.md:

    • explain_program5.py によって生成される、プログラムの目的と使用方法を説明するMarkdownファイル。

  6. [basename]_quality.md:

    • --prompt_quality オプションが指定された場合に explain_program5.py によって生成される、プログラムのコード品質評価を記述したMarkdownファイル。

  7. [basename]_examples.md:

    • プログラムの実行例を示すMarkdownファイル。

    • 対象スクリプトの --help 出力、および関連する画像ファイルやデータファイルへのリンクと埋め込みを含みます。

  8. [basename]_api.rst:

    • 対象PythonスクリプトのAPIリファレンスを自動生成するためのreStructuredTextファイル。

    • automodule ディレクティブを使用して、スクリプト内のクラス、関数、メソッド、Docstringを抽出します。

  9. [basename]_[YYYYMMDD].py:

    • Docstring追加処理が行われる前に、元の入力Pythonスクリプトが日付 (YYYYMMDD) 付きでバックアップされたファイル。

  10. [basename]_docstring.py:

    • add_docstring.py が一時的に生成するDocstring付きのPythonスクリプトファイル。

    • 処理完了後、このファイルは元の入力ファイルを上書きするために使用され、その後は空のダミーファイルに置き換えられます。

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

make_sphinx_files.py は、Sphinxドキュメント生成の一連のルーチン（Docstring追加、バックアップ、解説生成、RST作成）を自動化します。

python make_sphinx_files.py [-h] [--subdir SUBDIR] [--prompt_explain PROMPT_EXPLAIN] [--prompt_quality PROMPT_QUALITY] [--prompt_add_docstring PROMPT_ADD_DOCSTRING] [--api {openai,openai5,google,gemini}] [-u UPDATE] [-w OVERWRITE] [-p PAUSE] infile

引数:

  • infile

    • 説明: 対象となるPythonスクリプトファイル名。

    • 例: mu_fit.py

  • --subdir SUBDIR

    • 説明: source ディレクトリからの相対パスを指定します。__init__.py や _index.rst などのファイルがこのサブディレクトリ内に生成されます。指定がない場合、infile のパスから自動的に推測されます。

    • デフォルト: なし (自動推測)

  • --prompt_explain PROMPT_EXPLAIN

    • 説明: usage ドキュメント生成用プロンプトファイルのパス。

    • デフォルト: explain_program5.ini

  • --prompt_quality PROMPT_QUALITY

    • 説明: quality ドキュメント生成用プロンプトファイルのパス。このオプションが指定されない場合、品質評価はスキップされます。

    • デフォルト: prompt_quality.ini

  • --prompt_add_docstring PROMPT_ADD_DOCSTRING

    • 説明: add_docstring.py に渡すプロンプトファイルのパス。

    • デフォルト: 空文字列 (内部デフォルトプロンプトを使用)

  • --api {openai,openai5,google,gemini}

    • 説明: 使用するAIモデルのAPIを指定します。

    • 選択肢: openai, openai5, google, gemini

    • デフォルト: google

  • -u UPDATE, --update UPDATE

    • 説明: ドキュメント更新の挙動を制御します。1 の場合、入力ファイルがドキュメントファイルより新しい場合にのみ更新します。0 の場合、常に更新を試みます。

    • 型: 整数

    • デフォルト: 1

  • -w OVERWRITE, --overwrite OVERWRITE

    • 説明: 既存のファイルを上書きするかどうかを制御します。1 の場合、既存のドキュメントファイル（_index.rst など）を上書きします。0 の場合、既存のファイルがある場合はスキップします。

    • 型: 整数

    • デフォルト: 0

  • -p PAUSE, --pause PAUSE

    • 説明: 各ステップの実行後に一時停止するかどうかを制御します。1 の場合、一時停止します。

    • 型: 整数

    • デフォルト: 0

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

ここでは、my_script.py というPythonスクリプトを対象として、ドキュメントを生成する例を示します。

# my_script.py の内容例
"""
これはテストスクリプトです。
Docstringが自動で追加されることを期待します。
"""

import os

def hello_world(name: str) -> None:
    """
    指定された名前に挨拶を出力します。
    """
    print(f"Hello, {name}!")

def calculate_sum(a: int, b: int) -> int:
    """
    二つの整数を合計します。
    """
    return a + b

if __name__ == "__main__":
    print("My script started.")
    hello_world("Alice")
    result = calculate_sum(10, 20)
    print(f"Sum: {result}")

1. 最もシンプルな実行例

my_script.py を対象に、デフォルト設定でSphinxドキュメントファイルを生成します。カレントディレクトリに add_docstring.py と explain_program5.py、explain_program5.ini、prompt_quality.ini があることを前提とします。

python make_sphinx_files.py my_script.py

実行結果の説明: 上記のコマンドを実行すると、以下のようなファイルがカレントディレクトリに生成されます。

  • __init__.py

  • index.template

  • my_script_index.rst

  • my_script_download.rst

  • my_script_usage.md

  • my_script_quality.md (デフォルトの prompt_quality.ini を使用)

  • my_script_examples.md

  • my_script_api.rst

  • my_script_YYYYMMDD.py (元の my_script.py のバックアップ)

  • my_script.py (Docstringが追加されたバージョンに更新されます)

また、コンソールには各ステップの進行状況と、外部スクリプトの実行ログが表示されます。例えば、Docstring追加や解説生成のステップでは、AIモデルとの通信状況や結果が示されます。

2. 特定のサブディレクトリに生成し、Google Gemini APIを使用する例

source/my_project というサブディレクトリにドキュメントファイルを生成し、gemini APIを使用します。

python make_sphinx_files.py my_script.py --subdir my_project --api gemini

実行結果の説明: このコマンドは、カレントディレクトリに __init__.py と index.template を作成し、my_project というディレクトリが存在しない場合は作成します。そして、my_project ディレクトリ内に以下のファイルを生成します。

  • my_project/__init__.py (サブディレクトリ内の初期化ファイル)

  • my_project/my_script_index.rst

  • my_project/my_script_download.rst

  • my_project/my_script_usage.md

  • my_project/my_script_quality.md

  • my_project/my_script_examples.md

  • my_project/my_script_api.rst

元の my_script.py は、Docstringが追加されたバージョンに更新され、my_script_YYYYMMDD.py がバックアップとして残ります。AIモデルとしてGoogle Geminiが使用されます。

3. プロンプトファイルを指定し、既存ファイルを上書きする例

カスタムプロンプトファイル my_explain_prompt.ini と my_quality_prompt.ini を使用し、既存のドキュメントファイルを強制的に上書きします。

python make_sphinx_files.py my_script.py --prompt_explain my_explain_prompt.ini --prompt_quality my_quality_prompt.ini --overwrite 1

実行結果の説明: この場合、explain_program5.py は my_explain_prompt.ini を、explain_program5.py の品質評価機能は my_quality_prompt.ini をそれぞれプロンプトとして使用してドキュメントを生成します。 既に生成済みの my_script_usage.md や my_script_quality.md などのファイルが存在しても、--overwrite 1 が指定されているため、それらは新しい内容で上書きされます。 my_script.py 自体もDocstringが再追加される可能性があります（更新日時による）。