files2md_tags プログラム仕様

画像ファイルからサムネイルを生成し、Markdown形式の画像タグやファイルリンクを生成するスクリプト。

詳細説明:

位置引数で複数のワイルドカードを受け取り、指定されたファイルを処理します。 画像ファイルに対してはサムネイルを生成し、Markdownの画像一覧として出力します。 画像以外のファイルはデータファイルとして扱い、Markdownリンク一覧を出力します。 出力形式はSphinx / Markdownでそのまま利用しやすい構成になっています。

sphinx_.files2md_tags.expand_patterns(patterns: Iterable[str]) → list[Path]

概要:

複数のワイルドカードパターンを展開し、重複を除いたファイルパスのリストを返します。

詳細説明:

指定された各パターンにマッチするファイルを検索し、重複を排除してソートされたPathオブジェクトのリストとして返します。

引数:

param patterns:

展開するワイルドカードパターンのリスト。

type patterns:

Iterable[str]

戻り値:

returns:

重複を除いたPathオブジェクトのリスト。

rtype:

list[Path]

sphinx_.files2md_tags.format_data_section(files: list[Path]) → str

概要:

データファイルのリストからMarkdown形式のセクションを生成します。

詳細説明:

各ファイルへのリンクを含む「## 生成されたデータファイル」セクションを作成します。

引数:

param files:

データファイルのPathオブジェクトのリスト。

type files:

list[Path]

戻り値:

returns:

生成されたMarkdown文字列。ファイルがない場合は空文字列。

rtype:

str

sphinx_.files2md_tags.format_image_section(files: list[Path]) → str

概要:

画像ファイルのリストからMarkdown形式のセクションを生成します。

詳細説明:

各画像に対するサムネイル付きのリンクと、元の画像へのリンクを含む 「## 生成された画像一覧」セクションを作成します。

引数:

param files:

画像ファイルのPathオブジェクトのリスト。

type files:

list[Path]

戻り値:

returns:

生成されたMarkdown文字列。ファイルがない場合は空文字列。

rtype:

str

sphinx_.files2md_tags.is_image_file(path: Path) → bool

概要:

指定されたパスが画像ファイルであるかを判定します。

詳細説明:

ファイルの拡張子が定義済みの画像拡張子セットに含まれるかをチェックします。

引数:

param path:

チェック対象のファイルパス。

type path:

Path

戻り値:

returns:

画像ファイルであればTrue、そうでなければFalse。

rtype:

bool

sphinx_.files2md_tags.is_thumbnail_file(path: Path) → bool

概要:

指定されたパスがサムネイルファイルであるかを判定します。

詳細説明:

ファイル名が "-s" で終わるかをチェックします。

引数:

param path:

チェック対象のファイルパス。

type path:

Path

戻り値:

returns:

サムネイルファイルであればTrue、そうでなければFalse。

rtype:

bool

sphinx_.files2md_tags.main() → None

概要:

スクリプトのメイン処理を実行します。

詳細説明:

コマンドライン引数を解析し、指定されたファイルパターンに基づいて、 画像ファイルのサムネイル生成およびMarkdown形式のデータファイル/画像一覧の出力を実行します。

sphinx_.files2md_tags.make_thumbnail(src: Path, thumb: Path, width: int, overwrite: bool, update: bool) → bool

概要:

指定されたソース画像ファイルからサムネイル画像を生成します。

詳細説明:

サムネイルが既に存在する場合、overwriteまたはupdateフラグに基づいて処理を決定します。 updateがTrueの場合、ソース画像が新しい場合にのみサムネイルを更新します。

引数:

param src:

元となる画像ファイルのパス。

type src:

Path

param thumb:

生成するサムネイルファイルのパス。

type thumb:

Path

param width:

サムネイルの幅（ピクセル単位）。高さはアスペクト比を維持して自動計算されます。

type width:

int

param overwrite:

既存のサムネイルを強制的に上書きするかどうか。Trueの場合、既存ファイルは無条件に上書きされます。

type overwrite:

bool

param update:

元画像がサムネイルよりも新しい場合にのみサムネイルを更新するかどうか。Trueの場合、更新日時を比較します。

type update:

bool

戻り値:

returns:

サムネイルが新しく生成または更新された場合はTrue、それ以外はFalse。

rtype:

bool

例外:

raises ValueError:

ソース画像のサイズが無効な場合（幅または高さが0以下）。