burst_sphinx_indexes プログラム仕様
Sphinx toctree globパターン展開スクリプト。
- 概要:
Sphinxのtoctreeにおけるglobパターンを展開し、指定されたファイル群を自動的に挿入します。
- 詳細説明:
親のreStructuredTextファイル内の .. toctree:: ディレクティブにおいて、 ファイル名パターン（glob形式）が指定された場合、そのパターンに合致するファイルを 自動的に見つけ出し、toctreeのエントリとして挿入します。 Markdown (.md) と reStructuredText (.rst) ファイルの両方に対応します。 重複エントリの除外、エントリのソート、および子ファイルのセクションタイトルを ラベルとして使用するオプションをサポートします。
- 関連リンク:
burst_sphinx_index_usage
- converter.burst_sphinx_indexes.expand_glob_in_toctree(parent_rst: Path, sort_flag: bool, label_flag: bool, verbose: bool = False) str[ソース]
reStructuredTextファイル内のtoctreeにおけるglobパターンを展開して置換する。
- 詳細説明:
複数の .. toctree:: ディレクティブに対応し、globパターンに合致する子ファイルを toctreeエントリとして挿入した新しい内容を返します。 展開されたエントリのソートやラベル付けもサポートします。
- パラメータ:
parent_rst -- Path - globパターンを展開する対象の親reStructuredTextファイルのパス。
sort_flag -- bool - 展開されたエントリをファイル名でソートするかどうか。True の場合ソートされる。
label_flag -- bool - 展開されたエントリに子ファイルの最初のセクションタイトルをラベルとして使用するかどうか。True の場合ラベルが使用される。
verbose -- bool - 詳細ログを出力するかどうか。デフォルトは False。
- 戻り値:
str - globパターンが展開された後のreStructuredTextファイルの内容。
- converter.burst_sphinx_indexes.extract_first_section_title(path: Path, verbose: bool = False) str | None[ソース]
指定されたファイルから最初のセクションタイトルを抽出する。
- 詳細説明:
reStructuredText形式の下線見出し (----, ==== など) または Markdown形式のH1見出し (# Title) のいずれかをサポートします。
- パラメータ:
path -- Path - タイトルを抽出する対象ファイルのパス。
verbose -- bool - 詳細ログを出力するかどうか。デフォルトは False。
- 戻り値:
Optional[str] - 抽出されたタイトル文字列。タイトルが見つからない場合やエラーが発生した場合は None。
- converter.burst_sphinx_indexes.glob_with_extensions(parent_dir: Path, pattern: str, verbose: bool = False) List[Path][ソース]
Sphinxのtoctreeのglobルールに沿ってファイルを検索する。
- 詳細説明:
パターンに拡張子がない場合、.rst と .md の両方を補完してファイルを検索します。 拡張子が明示されている場合は、その拡張子のみで検索します。
- パラメータ:
parent_dir -- Path - 検索の基準となる親ディレクトリのパス。
pattern -- str - 検索するファイル名のglobパターン。
verbose -- bool - 詳細ログを出力するかどうか。デフォルトは False。
- 戻り値:
List[Path] - パターンにマッチしたファイルのパスのリスト。
- converter.burst_sphinx_indexes.indent_width(line: str) int[ソース]
行頭のインデント幅を計算して返す。
- 詳細説明:
タブ文字 (` `) は4文字分のスペースとして扱って計算します。
- パラメータ:
line -- str - インデント幅を計算する対象の行文字列。
- 戻り値:
int - 行頭のインデント幅。
- converter.burst_sphinx_indexes.log(verbose: bool, message: str)[ソース]
verboseモードが有効な場合に標準エラー出力に情報メッセージを出力する。
- パラメータ:
verbose -- bool - メッセージを出力するかどうかを決定するフラグ。
message -- str - 出力する情報メッセージ。
- 戻り値:
None