make_sphinx_files プログラム仕様
Sphinxドキュメント自動生成スクリプト。
指定されたPythonスクリプトファイルに対して、Docstringの追加、プログラム解説の生成、 Sphinx用の各種RST/MDファイルの作成、および関連するファイルのバックアップと置換を自動化します。 add_docstring.py と explain_program5.py を利用して、AIによるドキュメント生成を行います。
- ai.make_sphinx_files.initialize()[ソース]
コマンドライン引数パーサーを初期化し、設定します。
argparse.ArgumentParser オブジェクトを生成し、スクリプトの説明、 必要な引数 (infile)、およびオプション引数 (subdir, api, update, overwrite, pause) を定義します。
- 戻り値:
設定済みの ArgumentParser オブジェクト。
- ai.make_sphinx_files.main(args)[ソース]
Sphinxドキュメント生成の主要な処理を実行します。
入力ファイルから基本情報を抽出し、__init__.py, index.template, _index.rst, _api.rst, _examples.md といったSphinx関連ファイルを生成します。 その後、explain_program5.py と add_docstring.py を実行して、 プログラム解説とDocstringを生成・追加し、最後に元のファイルをバックアップし、 Docstringが追加されたファイルで置き換えます。
- パラメータ:
args -- コマンドライン引数を格納した argparse.Namespace オブジェクト。
- ai.make_sphinx_files.make_api_rst(api_rst, base_name, package_path)[ソース]
SphinxのAPIドキュメント (_api.rst) ファイルを作成します。
指定された base_name と package_path を使用して、 PythonモジュールのAPIリファレンスとなる .rst ファイルを作成します。 automodule ディレクティブを用いて、自動的にメンバー、非公開メンバー、継承情報を抽出する設定を行います。
- パラメータ:
api_rst -- 作成するAPI .rst ファイルのパス。
base_name -- ベースとなるファイル名（拡張子なし）。
package_path -- Pythonパッケージのフルパス。
- ai.make_sphinx_files.make_examples_md(examples_md, infile, base_name)[ソース]
実行例を示すMarkdownファイル (_examples.md) を作成します。
指定された infile に対して --help オプションを実行してヘルプ出力を取得し、 現在のディレクトリ内の関連する画像ファイルやデータファイルを検出し、 それらを組み込んだMarkdown形式の実行例ファイルを作成します。
- パラメータ:
examples_md -- 作成する実行例Markdownファイルのパス。
infile -- ヘルプ出力を取得する対象のPythonスクリプトファイル。
base_name -- ベースとなるファイル名（拡張子なし）。
- ai.make_sphinx_files.make_index_rst(index_rst, base_name, package_path)[ソース]
Sphinxのモジュール別インデックス (_index.rst) ファイルを作成します。
指定された base_name と package_path を使用して、 モジュールごとのドキュメントのトップページとなる .rst ファイルを作成します。 このファイルには、usage, examples, apiへのリンクを含むtoctreeが定義されます。
- パラメータ:
index_rst -- 作成する .rst ファイルのパス。
base_name -- ベースとなるファイル名（拡張子なし）。
package_path -- Pythonパッケージのフルパス。
- ai.make_sphinx_files.make_index_template(path, module_path)[ソース]
index.template ファイルを作成または更新します。
プロジェクト全体のSphinxインデックスファイルとなる index.template を作成または追記します。 ファイルが存在しない場合は新規作成し、基本的なtoctree構造を含みます。 存在する場合は、指定された module_path をtoctreeに追加します。
- パラメータ:
path -- index.template ファイルのパス。
module_path -- Sphinxドキュメントのインデックスに追加するモジュールパス。
- ai.make_sphinx_files.make_init_py(path)[ソース]
指定されたパスに __init__.py ファイルを作成します。
既にファイルが存在する場合はその旨を表示し、存在しない場合は空の __init__.py ファイルを作成します。 これはPythonパッケージとして認識させるために必要です。
- パラメータ:
path -- __init__.py を作成するパス。
- ai.make_sphinx_files.read_args(parser)[ソース]
コマンドライン引数を解析し、整形して返します。
与えられた ArgumentParser を使用してコマンドライン引数を解析します。 subdir が指定されていない場合は relative_from_source 関数を使って自動的に設定します。 解析された引数を表示し、argparse.Namespace オブジェクトとして返します。
- パラメータ:
parser -- argparse.ArgumentParser オブジェクト。
- 戻り値:
解析された引数を格納する argparse.Namespace オブジェクト。
- ai.make_sphinx_files.relative_from_source(argv0: str) str[ソース]
ファイルパスから'source'ディレクトリ以下の相対パスを取得する。
指定されたファイルパスを解決し、そのパス中に 'source' ディレクトリがあれば、 その直下からの相対パス（ファイル名を除いたディレクトリ部分）を返す。 'source' が見つからない場合は空文字列を返す。
- パラメータ:
argv0 -- プログラムのパス。通常 sys.argv[0] が渡される。
- 戻り値:
'source' ディレクトリ以下の相対パスの文字列。
- ai.make_sphinx_files.run_step(message, cmd_list)[ソース]
作業ステップを表示し、外部コマンドを実行します。
指定されたメッセージを表示した後、subprocess.run を使用してコマンドリストを実行します。 コマンドの実行結果が成功（終了コード0）であれば True を返し、 エラーが発生した場合はエラーメッセージを表示して False を返します。
- パラメータ:
message -- 実行するステップのメッセージ。
cmd_list -- 実行するコマンドとその引数を要素とするリスト。
- 戻り値:
コマンドが正常に実行された場合は True、それ以外は False。