docx2md プログラム仕様

docx2md.py

概要: Wordファイル（.docx）をMarkdown形式に変換するスクリプトです。

詳細説明: このスクリプトは、Word文書からテキスト、画像、数式、テーブル、リスト、見出しなどのコンテンツを抽出し、対応するMarkdown形式に変換します。数式はOMML（Office Math Markup Language）からLaTeX形式に変換され、インライン数式は`$...$`、ディスプレイ数式は`$$n...n$$`として出力されます。画像は指定されたディレクトリに保存され、Markdown内に相対パスでリンクされます。

関連リンク: docx2md.py 技術ドキュメント

converter.docx2md.convert(infile_path: str, outfile_path: str, imagedir: str)[ソース]

DOCXファイルをMarkdownに変換するメイン関数です。

詳細説明: 指定された入力DOCXファイルを読み込み、その内容を走査してMarkdownに変換します。段落とテーブルはそれぞれ handle_paragraph と handle_table 関数で処理されます。画像は imagedir で指定されたディレクトリに保存され、Markdown内から相対パスで参照されます。 python-docx のバージョンによっては iter_inner_content が存在しない場合があるため、その場合はフォールバックとして doc.element.body を直接処理します。

パラメータ:

infile_path -- str: 入力Wordファイル（.docx）のパス。
outfile_path -- str: 出力Markdownファイル（.md）のパス。
imagedir -- str: 画像を保存するディレクトリの名前。出力Markdownファイルからの相対パス。

戻り値:

None

converter.docx2md.get_formatted_cell_text(cell: _Cell) → str[ソース]

テーブルのセル内のテキストを、書式を保持したMarkdown文字列として取得します。セル内の改行は <br> で処理します。

詳細説明: Wordのテーブルセルは複数の段落を含むことができます。この関数は、セル内の各段落を process_runs_to_markdown を使用してMarkdownに変換し、段落間の改行をMarkdownの <br> タグで表現することで、セル内のレイアウトを保持します。

パラメータ:: cell -- docx.table._Cell: 処理対象のテーブルセルオブジェクト。
戻り値:: str: セル内のコンテンツをMarkdown形式で表現した文字列。

converter.docx2md.handle_paragraph(para: Paragraph, doc: Document, media_dir: str, list_counters: dict) → str[ソース]

単一の段落を処理し、Markdown文字列を返します。

詳細説明: 段落の内容（画像、ブロック数式、見出し、リスト、通常テキスト）を識別し、それぞれに対応するMarkdown形式に変換します。 - 画像段落: save_image_from_run を使用して画像を保存し、Markdownタグを生成。 - ブロック数式: omml_to_latex を使用してLaTeXに変換し、$$...$$ で囲む。 - 見出し: 段落スタイルに基づいて # の数を決定。 - リスト: numPr 要素を解析し、リストカウンター (list_counters) を管理して番号付き・箇条書きリストを生成。 - 通常テキスト: process_runs_to_markdown を使用してテキストとインライン数式の混在を処理。

パラメータ:

para -- docx.text.paragraph.Paragraph: 処理対象の段落オブジェクト。
doc -- docx.document.Document: 親となるDocumentオブジェクト。画像抽出に使用されます。
media_dir -- str: 画像を保存するディレクトリのパス。
list_counters -- dict: リストの階層レベルごとのカウンターを保持する辞書。

戻り値:

str: 変換されたMarkdown文字列。

converter.docx2md.handle_table(table: Table) → str[ソース]

テーブルをMarkdown形式に変換します。

詳細説明: Wordのテーブルオブジェクトを受け取り、Markdownのテーブル記法に変換します。最初の行はヘッダーとして扱い、その下に区切り線 (---) を挿入します。各セル内のコンテンツは get_formatted_cell_text を使用して、書式とセル内改行を保持したMarkdownとして取得されます。

パラメータ:: table -- docx.table.Table: 処理対象のテーブルオブジェクト。
戻り値:: str: 変換されたMarkdown形式のテーブル文字列。

converter.docx2md.is_inline_math(item) → bool[ソース]

指定されたアイテムがインライン数式（m:oMath）であるかチェックします。

詳細説明: この関数は、python-docx の Run オブジェクトまたは lxml の要素のいずれかを受け取り、その内部に m:oMath 要素が含まれているかを判断します。これにより、テキストコンテンツと数式コンテンツを適切に区別して処理できます。

パラメータ:: item -- docx.text.run.Run | lxml.etree._Element: チェック対象のアイテム。
戻り値:: bool: アイテムがインライン数式を含む場合はTrue、そうでない場合はFalse。

converter.docx2md.iter_runs_and_omath_in_order(para: Paragraph)[ソース]

段落内で、XMLの出現順に <w:r> 要素は python-docx の Run オブジェクトとして、 <m:oMath> 要素は lxml の要素のまま返すジェネレータです。

詳細説明: Word文書の段落はテキスト（Run）と数式（oMath）が混在していることがあります。このジェネレータは、これらの要素をWord内部のXML構造での出現順序に従って提供することで、元の文書のコンテンツフローを維持したまま処理を可能にします。

パラメータ:: para -- docx.text.paragraph.Paragraph: 処理対象の段落オブジェクト。
Yields:: docx.text.run.Run | lxml.etree._Element: Run オブジェクトまたは lxml の数式要素。

converter.docx2md.main()[ソース]

コマンドライン引数を処理し、DOCXからMarkdownへの変換を実行します。

詳細説明: argparse モジュールを使用して、入力ファイル、出力ファイル、画像保存ディレクトリ、および終了時の一時停止オプションをコマンドライン引数から受け取ります。これらの引数に基づいて convert 関数を呼び出し、変換処理を開始します。

戻り値:: None

converter.docx2md.omml_to_latex(omath_para_element: _Element) → str[ソース]

段落要素（<w:p>）を受け取り、その中の最初の m:oMath 要素をLaTeXに変換します。

詳細説明: 与えられたXML段落要素を走査し、最初に見つかったOffice Math Markup Language (m:oMath) 要素を抽出します。その数式要素を parse_omml_element 関数に渡し、対応するLaTeX文字列を生成します。これにより、段落内に埋め込まれた数式がインラインまたはディスプレイ形式で表現されます。

パラメータ:: omath_para_element -- lxml.etree._Element: m:oMath 要素を含む可能性のあるXML段落要素。
戻り値:: str: 変換されたLaTeX文字列。数式が見つからない場合は空文字列。

converter.docx2md.paragraph_contains_math(para: Paragraph) → bool[ソース]

段落要素に数式（m:oMath）が含まれているかチェックします。

詳細説明: Wordの段落オブジェクト（Paragraph）を内部のXML要素として走査し、 Office Math Markup Language (m:oMath) タグが存在するかを調べます。これにより、段落が数式のみで構成されているか、または数式が混在しているかを判断できます。

パラメータ:: para -- docx.text.paragraph.Paragraph: チェック対象の段落オブジェクト。
戻り値:: bool: 段落に数式が含まれる場合はTrue、そうでない場合はFalse。

converter.docx2md.parse_omml_element(element: _Element) → str[ソース]

OMML (Office Math Markup Language) のXML要素を再帰的に解析し、LaTeX文字列に変換します。

詳細説明: lxml ライブラリを使用してWord文書内の数式XML構造をトラバースし、各OMMLタグ（m:t, m:f, m:sSup, m:d, m:nary など）を対応するLaTeX構文にマッピングします。 SYMBOL_MAP を用いて記号の変換も行います。

パラメータ:: element -- lxml.etree._Element: 解析対象のOMML XML要素。
戻り値:: str: 変換されたLaTeX文字列。

converter.docx2md.process_runs_to_markdown(items) → str[ソース]

Run オブジェクトと lxml 要素（m:oMath）の混在リストを受け取り、Markdown文字列を返します。

詳細説明: 与えられた要素のリストを、スタイル（太字、斜体、上付き、下付き）とコンテンツタイプ（テキスト、数式）に基づいてグループ化し、それぞれのグループを適切なMarkdown形式に変換して結合します。数式は parse_omml_element を用いてLaTeXに変換され、$ または $$ で囲まれます。 Pandoc互換の上付き・下付き記法 (^text^, ~text~) もサポートします。

パラメータ:: items -- list[docx.text.run.Run | lxml.etree._Element]: Run オブジェクトと lxml 数式要素のリスト。
戻り値:: str: 結合されたMarkdown形式の文字列。

converter.docx2md.save_image_from_run(run, doc: Document, media_dir: str) → str | None[ソース]

Run 要素から画像を抽出し、指定されたディレクトリに保存します。画像のMarkdownタグを返します。

詳細説明: Word文書内の`Run`要素に含まれる埋め込み画像 (<a:blip>) を特定し、関連する画像データを抽出し、バイナリファイルとして media_dir に保存します。保存された画像への相対パスを含むMarkdown形式の画像タグ (![alt_text](path/to/image.png)) を生成します。

パラメータ:

run -- docx.text.run.Run: 画像を含む可能性のある`Run`オブジェクト。
doc -- docx.document.Document: 親となるDocumentオブジェクト。画像パーツの参照に使用されます。
media_dir -- str: 画像を保存するディレクトリのパス。

戻り値:

str | None: 画像のMarkdownタグ。画像が見つからない、または保存に失敗した場合はNone。