make_sphinx_files.py ドキュメント

プログラムの動作

make_sphinx_files.py は、PythonスクリプトのSphinxドキュメント生成プロセスを自動化するためのユーティリティです。このプログラムは、以下の主要なタスクを実行します。

  • Sphinx用ファイル構造の初期化: __init__.py ファイルや、Sphinxのメインインデックスファイル (index.template)、モジュールごとのインデックスファイル (<basename>_index.rst) を作成します。

  • ソースコードの提供: 元のPythonスクリプトをダウンロード可能にし、Sphinxドフィニメント内にコードブロックとして埋め込むための .rst ファイル (<basename>_download.rst) を生成します。

  • APIドキュメントの生成: Sphinxの automodule 機能を利用して、指定されたPythonスクリプトのAPIリファレンス (<basename>_api.rst) を自動生成します。

  • 実行例ドキュメントの生成: スクリプトの --help 出力、関連する画像ファイル、データファイルを自動的に収集し、実行例としてMarkdownファイル (<basename>_examples.md) を作成します。

  • LLMを活用したドキュメント生成: 外部のLLM(大規模言語モデル)ベースのPythonスクリプト (explain_program5.py および add_docstring.py) を呼び出し、以下のドキュメントを生成または更新します。

    • プログラムの目的や使い方を説明するMarkdownファイル (<basename>_usage.md)。

    • コード品質に関する評価を記述するMarkdownファイル (<basename>_quality.md)。

    • オリジナルのPythonスクリプトにDocstringを自動的に追加し、更新する。元のファイルはバックアップされます。

このプログラムは、一連のドキュメント生成ステップを連携させ、開発者が簡単にSphinxドキュメントを構築できるようにすることで、ドキュメント作成の手間を軽減し、一貫性を保つことを目的としています。

原理

make_sphinx_files.py は、複数のPythonスクリプトとSphinxの機能を組み合わせてドキュメントを生成します。

  1. ファイル管理とパス解決: os および pathlib モジュールを使用して、スクリプトのパス、出力ファイルのパス、およびモジュール名を適切に解決します。特に relative_from_source 関数は、source ディレクトリからの相対パスを計算し、Sphinxの構造に適合させます。

  2. Sphinxファイル構造の生成:

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

    • make_index_template: Sphinxプロジェクトのルートディレクトリに配置される index.template ファイルを生成または更新し、各モジュールのインデックスファイルへの参照を追加します。

    • make_index_rst: 各Pythonスクリプトに対応するトップレベルのインデックスファイル (<basename>_index.rst) を作成します。これには、ダウンロード、使用法、品質、実行例、APIリファレンスへの参照が含まれます。

    • make_download_rst: literalinclude ディレクティブを使用して、Pythonスクリプトのソースコードをそのままドキュメントに埋め込みます。また、 :download: ロールを用いて、ユーザーがファイルを直接ダウンロードできるリンクを提供します。

    • make_api_rst: automodule ディレクティブと currentmodule ディレクティブを組み合わせて、指定されたPythonモジュールのクラス、関数、メソッドなどのAPIドキュメントを自動的に抽出して生成します。

  3. 実行例の収集: make_examples_md 関数では、対象のPythonスクリプトを subprocess.run で実行し、--help オプションの出力をキャプチャします。また、ファイルシステムをスキャンして、対象のスクリプト名で始まる画像ファイル(.png, .jpg, .jpeg)やデータファイル(.csv, .xlsx など)を見つけ、それらをMarkdownドキュメントにリストアップし、画像は埋め込み表示します。

  4. 外部LLMスクリプトとの連携: subprocess.run を使用して、別のPythonスクリプト explain_program5.py および add_docstring.py を子プロセスとして呼び出します。

    • explain_program5.py は、指定されたPythonスクリプトのコードを解析し、LLMの助けを借りてプログラムの動作説明 (<basename>_usage.md) やコード品質評価 (<basename>_quality.md) をMarkdown形式で生成します。

    • add_docstring.py は、LLMの助けを借りて、指定されたPythonスクリプトの関数やクラスにDocstring(3重引用符で囲まれたドキュメント文字列)を自動的に追加します。 これらの外部スクリプトに、LLMの種類 (--api)、モデル名 (--model)、推論の強度 (--reasoning-effort)、およびカスタムプロンプトファイル (--inifile) などの引数を渡すことで、生成内容を制御します。

  5. ファイル更新の管理: check_updated 関数は、ファイルの最終更新日時を比較し、ソースファイルがドキュメントファイルより新しい場合にのみ、LLMによる生成プロセスを実行します。これにより、不要なLLM呼び出しを避け、効率を向上させます。

  6. ファイル操作とバックアップ: Docstringが追加された新しいファイルは、元のファイル名で保存される前に、元のファイルがバックアップ (<basename>_<date>.py) されます。Docstring生成が成功した場合、一時ファイルは削除され、元のファイルが更新されます。

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

make_sphinx_files.py 自体はPythonの標準ライブラリのみを使用しており、特別なpipインストールは不要です。

しかし、このプログラムが連携して動作する外部スクリプト (add_docstring.py と explain_program5.py) は、LLM(大規模言語モデル)のAPIにアクセスするために以下のライブラリを必要とします。

  • LLM APIクライアントライブラリ:

    • OpenAI APIを使用する場合: openai

    • Google Gemini APIを使用する場合: google-generativeai

これらのライブラリは、以下のコマンドでインストールできます。

pip install openai google-generativeai

また、生成されたSphinxドキュメントをビルドするためには、Sphinx自体とその関連拡張機能が必要です。

  • Sphinx: ドキュメントビルドシステム

  • MyST-Parser: MarkdownファイルをSphinxで利用可能にするためのパーサー(.mdファイルを出力するため)

これらのライブラリは、以下のコマンドでインストールできます。

pip install sphinx myst-parser

必要な入力ファイル

make_sphinx_files.py は以下のファイルを主に入力として使用します。

  1. 対象のPythonスクリプト (infile):

    • 説明、APIリファレンス、Docstringの追加の対象となるPythonのソースコードファイルです。

    • 例: my_program.py

  2. プロンプト設定ファイル (.ini形式):

    • LLMに与えるプロンプトの内容や、生成に関する設定を記述したINI形式のファイルです。

    • --prompt_explain で指定: explain_program5.py に渡され、プログラムの動作説明 (_usage.md) を生成するために使用されます。デフォルトは explain_program5.ini。

    • --prompt_quality で指定: explain_program5.py に渡され、コード品質評価 (_quality.md) を生成するために使用されます。デフォルトは prompt_quality.ini。

    • --prompt_add_docstring で指定: add_docstring.py に渡され、Docstringを追加する際の指示をLLMに与えるために使用されます。デフォルトは空文字列。

  3. 既存の index.template (任意):

    • Sphinxプロジェクトのメインインデックスファイルで、もし存在すれば、新しいモジュールのインデックス参照が追記されます。存在しない場合は新規作成されます。

  4. 関連する画像・データファイル (任意):

    • make_examples_md 関数が実行される際、対象スクリプトと同じディレクトリ内で、スクリプト名で始まる画像ファイル(例: my_program_plot.png)やデータファイル(例: my_program_results.csv)を自動的に検出し、_examples.md にリストアップし、画像を埋め込みます。

生成される出力ファイル

make_sphinx_files.py は、指定されたPythonスクリプトのベース名 (<basename>) に基づいて、以下のファイルを生成します。

  • __init__.py:

    • Pythonパッケージとして認識させるための空のファイル。

  • index.template:

    • Sphinxプロジェクトのメインインデックスファイル。新規作成されるか、既存ファイルに追記されます。

  • <basename>_index.rst:

    • 特定のPythonスクリプトのドキュメントのトップレベルインデックスファイル。他の .rst や .md ファイルへのリンクを含みます。

  • <basename>_download.rst:

    • 元のPythonスクリプトのソースコードをダウンロード可能にし、Sphinxドキュメント内に埋め込むためのファイル。

  • <basename>_api.rst:

    • 元のPythonスクリプトのAPIリファレンス(クラス、関数、メソッドなど)を自動生成するためのSphinxの automodule ディレクティブを含むファイル。

  • <basename>_examples.md:

    • 対象スクリプトの --help 出力、およびスクリプト名で始まる関連する画像ファイルやデータファイルをリストアップ・表示するMarkdown形式の実行例ドキュメント。

  • <basename>_usage.md:

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

  • <basename>_quality.md:

    • explain_program5.py によって生成される、プログラムのコード品質に関する評価や改善点を記述するMarkdownファイル(--prompt_quality が指定された場合のみ)。

  • <basename>_docstring.py:

    • add_docstring.py がDocstringを追加した後に一時的に作成されるファイル。処理が正常に完了すると、このファイルの内容は元の infile に上書きされ、このファイル自体は空のダミーファイルになります。

  • <basename>_<YYYYMMDD>.py:

    • add_docstring.py によるDocstring追加処理が実行される前に、元のPythonスクリプトのバックアップとして作成されるファイル。

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

make_sphinx_files.py の基本的な使い方は以下の通りです。

python make_sphinx_files.py <infile> [オプション]

引数:

  • <infile>: ドキュメント化の対象となるPythonスクリプトファイル名(例: mu_fit.py)。

オプション:

  • --subdir SUBDIR: source ディレクトリからの相対パス。Sphinxのモジュールパス解決に使用されます。省略すると、infile のパスから自動的に推測されます。

  • --prompt_explain PROMPT_EXPLAIN: explain_program5.py に渡す、使用法生成用のプロンプトファイルのパス。デフォルトは explain_program5.ini。

  • --prompt_quality PROMPT_QUALITY: explain_program5.py に渡す、コード品質評価生成用のプロンプトファイルのパス。デフォルトは prompt_quality.ini。

  • --prompt_add_docstring PROMPT_ADD_DOCSTRING: add_docstring.py に渡すプロンプトファイルのパス。デフォルトは空文字列。

  • --api {openai,openai5,google,gemini,lmstudio}: 子LLMプログラムに渡すAPI種別。デフォルトは google。

  • --model MODEL: 子LLMプログラムに渡すモデル名。例: gpt-4-turbo または qwen/qwen3.8-27b。省略時は、API種別に応じたデフォルトモデルが使用されます。

  • --reasoning-effort {low,medium,xhigh}: LM StudioのQwen3.8用推論量。--api lmstudio と組み合わせて指定する必要があります。省略時はモデル既定値。

  • --update_index UPDATE_INDEX (-u のエイリアスではありません): インデックスファイルを強制的に更新するかどうか (0: しない, 1: する)。

  • -u, --update UPDATE: LLMによるコンテンツ生成を更新するかどうか (0: しない, 1: する)。デフォルトは 1。

  • -w, --overwrite OVERWRITE: 既存のファイル(LLM生成結果)を上書きするかどうか (0: しない, 1: する)。デフォルトは 0。

  • -p, --pause PAUSE: LLMプログラム実行後に一時停止するかどうか (0: しない, 1: する)。デフォルトは 0。

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

ここでは、my_script.py というPythonスクリプトをドキュメント化する具体的な例を示します。

例1: 基本的なドキュメント生成

python make_sphinx_files.py my_script.py

このコマンドは、my_script.py を対象として、my_script_index.rst, my_script_download.rst, my_script_api.rst, my_script_examples.md, my_script_usage.md を生成します。__init__.py と index.template も必要に応じて作成または更新されます。Docstringはデフォルトプロンプトを使用して追加され、元の my_script.py は更新され、my_script_YYYYMMDD.py という名前でバックアップされます。LLM APIとしてはGoogle Geminiがデフォルトで使用されます。

例2: OpenAI APIを使用し、カスタムモデルと品質評価プロンプトを指定

python make_sphinx_files.py my_script.py --api openai --model gpt-4-turbo-preview --prompt_quality my_quality_prompt.ini

この例では、以下の動作が追加または変更されます。

  • LLM APIとしてOpenAIが使用され、gpt-4-turbo-preview モデルが指定されます。

  • my_quality_prompt.ini をプロンプトファイルとして使用し、my_script_quality.md が生成されます。

  • my_script_usage.md はデフォルトの explain_program5.ini を使用して生成されます。

  • Docstringはデフォルトプロンプトを使用して追加されます。

例3: source サブディレクトリ内のスクリプトをドキュメント化

source/analysis/my_analysis.py というパスにスクリプトがある場合:

python make_sphinx_files.py source/analysis/my_analysis.py --subdir analysis

または、--subdir を省略して自動検出させることもできます。

python make_sphinx_files.py source/analysis/my_analysis.py

この場合、モジュールパスは analysis.my_analysis となり、出力ファイルは my_analysis_index.rst などが source/analysis/ ディレクトリに生成されます。

例4: LLM処理のスキップとファイル上書き

python make_sphinx_files.py my_script.py -u 0 -w 1 --prompt_quality my_quality_prompt.ini
  • -u 0: 既存のドキュメントファイルが新しい場合、LLMによる _usage.md とDocstring追加の処理をスキップします。

  • -w 1: もしLLM処理が実行される場合、既存の出力ファイル(例: my_script_usage.md)を強制的に上書きします。

  • --prompt_quality my_quality_prompt.ini: my_script_quality.md は生成されます(-u 0 は prompt_quality の生成には影響しないため)。

これらのコマンドを実行すると、指定された設定に基づき、様々なSphinxドキュメントファイルがカレントディレクトリまたは指定されたサブディレクトリに生成され、対象のPythonスクリプトが更新されます。その後、ユーザーはSphinxのビルドコマンドを実行してHTMLやPDFなどの最終的なドキュメントを生成できます。

sphinx-build -b html . _build

この時、conf.py ファイルで myst_parser や sphinx.ext.autodoc などの拡張機能を有効にし、適切なパス設定が行われている必要があります。