make_sitemap_from_path.py 技術ドキュメント

プログラムの動作

make_sitemap_from_path.py は、指定されたディレクトリ以下にあるHTMLファイルを走査し、それらを一覧表示するHTML形式のサイトマップを自動生成するPythonスクリプトです。

プログラムの目的

Webサイトの階層構造を視覚的に把握できるサイトマップを簡単に作成することで、手作業によるサイトマップの作成・更新にかかる手間を削減します。特に、大規模なWebサイトや頻繁に更新されるサイトにおいて、サイト構造の管理を効率化することを目的としています。

主な機能

  1. HTMLファイルの再帰的探索: 指定されたルートディレクトリから、サブディレクトリを含めてすべてのHTMLファイルを探索します。

  2. タイトル抽出: 各HTMLファイルから <title> タグの内容を抽出し、サイトマップ内のリンクテキストとして使用します。<title> タグが見つからない場合は、ファイル名を代替タイトルとして使用します。

  3. 除外フィルタリング: 正規表現パターンを指定することで、特定のディレクトリやファイルをサイトマップから除外できます。これにより、開発中のファイルやプライベートなコンテンツがサイトマップに含まれることを防ぎます。

  4. HTMLサイトマップの生成: 探索・抽出された情報に基づき、HTML5形式のサイトマップファイルを生成します。各エントリは、ページのタイトルとルートディレクトリからの相対パスで構成され、一覧性の高いリスト形式で表示されます。

解決する課題

  • Webサイトのページが増えるたびに手動でサイトマップを更新する手間。

  • サイト全体の構造を一覧で把握したいが、個々のリンクをたどるのは非効率。

  • 特定のディレクトリやファイルをサイトマップに含めたくない場合の柔軟な対応。

原理

make_sitemap_from_path.py は、以下のアルゴリズムと技術を使用してサイトマップを生成します。

1. ファイル探索

os.walk() 関数を使用して、指定されたルートディレクトリからすべてのサブディレクトリとファイルを再帰的に走査します。 これにより、ディレクトリツリー全体を効率的に探索できます。

2. 除外パターンの適用

コマンドライン引数 --exclude で指定された正規表現パターンは、re.compile() を用いて正規表現オブジェクトにコンパイルされます。 ファイル探索中、各ディレクトリパスおよびファイルパスに対してこれらの正規表現パターンとのマッチング（re.search()）を行います。 いずれかのパターンに一致した場合、そのディレクトリまたはファイルはサイトマップの対象から除外されます。 これにより、特定のパスを持つファイルを柔軟にフィルタリングできます。

3. HTMLファイル判定

探索されたファイルのうち、ファイル名が .html (大文字・小文字を問わない) で終わるもののみをHTMLファイルとして認識します。

4. タイトル抽出

HTMLファイルからタイトルを抽出するために、以下の正規表現を使用します。

r"<title>(.*?)</title>"

この正規表現は、<title> タグとその内容を非貪欲に (.*?) 捕捉します。re.IGNORECASE フラグにより大文字・小文字を区別せずマッチングし、re.DOTALL フラグにより . が改行文字にもマッチするようにします。 re.search() でマッチしたグループ1の内容を抽出することで、ページのタイトルを取得します。ファイルが読み取れない場合や <title> タグが見つからない場合は、フォールバックとしてファイル名自体をタイトルとして使用します。エンコーディングエラーが発生しても処理が停止しないよう errors="ignore" を指定して読み込みます。

5. 相対パスの生成

pathlib.Path オブジェクトの relative_to() メソッドを使用して、各HTMLファイルのパスをルートディレクトリからの相対パスに変換します。 さらに as_posix() メソッドを呼び出すことで、Windows環境などでもパスセパレータを / に統一し、Webリンクとして適切に機能するようにします。

6. サイトマップの構造

生成されるサイトマップは、標準的なHTML5の構造に従います。 <ul> (順序なしリスト) と <li> (リストアイテム) を用いて各ページへのリンクをリスト形式で表示します。各リストアイテムは、抽出されたタイトルと、そのページの相対パスを含む <a> (アンカー) タグで構成されます。

\[{HTML} \rightarrow <ul> \rightarrow <li><a\ href='relative\_path'>Title</a> (relative\_path)</li>\]

これにより、視覚的に分かりやすい形でサイト構造が提示されます。

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

make_sitemap_from_path.py は、Pythonの標準ライブラリ (os, argparse, pathlib, re) のみを使用しており、追加でインストールが必要な非標準ライブラリはありません。

必要な入力ファイル

このプログラムの入力は、サイトマップを生成したい対象となるHTMLファイル群を含むディレクトリです。

  • ファイルの種類: .html または .HTML などの拡張子を持つHTMLファイル。

  • ファイルの内容: 特に厳密なHTML形式は求められませんが、<title> タグが存在するHTMLファイルであれば、その内容がサイトマップのリンクタイトルとして使用されます。<title> タグがない場合は、ファイル名が代替タイトルとして使用されます。

  • データ構造: ディレクトリ構造は任意です。プログラムは指定されたルートディレクトリ以下を再帰的に探索します。

生成される出力ファイル

プログラムは、指定されたパスにHTML形式のサイトマップファイルを出力します。

  • ファイル名: デフォルトは sitemap.html ですが、コマンドライン引数で任意のファイル名を指定できます。

  • ファイル形式: HTML5形式のファイル。

  • 内容:

    • <!DOCTYPE html> 宣言。

    • <head> セクションには utf-8 の文字エンコーディング指定と <title>Site Map</title> が含まれます。

    • <body> セクションには、<h1>Site Map</h1> という大見出しがあります。

    • 見つかったすべてのHTMLファイルへのリンクが、<ul> リスト内に <li> 要素として含まれます。

    • 各 <li> 要素は <a> タグを含み、href 属性にはルートディレクトリからの相対パスが、リンクテキストには抽出されたページのタイトルが設定されます。リンクの横には便宜的に相対パスも表示されます。 例: <li><a href='path/to/page.html'>Page Title</a> (path/to/page.html)</li>

    • サイトマップ内のファイルリストは、パスに基づいてアルファベット順にソートされます。

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

make_sitemap_from_path.py は、以下の書式でコマンドラインから実行します。

python make_sitemap_from_path.py [root_directory] [output_file] [--exclude pattern1 pattern2 ...]

引数

  • root_directory:

    • 説明: HTMLファイルの検索を開始するルートディレクトリのパスを指定します。

    • デフォルト: 指定しない場合、現在の作業ディレクトリ (.) が使用されます。

  • output_file:

    • 説明: 生成されるサイトマップファイルの出力ファイル名を指定します。

    • デフォルト: 指定しない場合、sitemap.html という名前で出力されます。

  • --exclude pattern1 pattern2 ...:

    • 説明: サイトマップから除外したいディレクトリパスやファイルパスに一致する正規表現パターンを1つ以上指定します。これらのパターンに一致するパスはサイトマップに含まれません。

    • デフォルト: 指定しない場合、_vti_cnf というパターンがデフォルトで除外されます。

    • 注意: 複数のパターンを指定する場合は、スペースで区切って記述します。

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

1. 基本的な使用例 (カレントディレクトリを検索し、デフォルトのファイル名で出力)

python make_sitemap_from_path.py

実行結果の説明: 現在の作業ディレクトリ (.) 以下にあるすべてのHTMLファイルを探索し、sitemap.html というファイル名でサイトマップを生成します。除外パターンはデフォルトの _vti_cnf のみが適用されます。

2. 特定のディレクトリを検索し、出力ファイル名を指定する例

python make_sitemap_from_path.py my_website_root custom_sitemap.html

実行結果の説明: my_website_root というディレクトリ以下を検索対象とし、生成されたサイトマップを custom_sitemap.html というファイル名で出力します。除外パターンはデフォルトの _vti_cnf のみが適用されます。

3. 除外パターンを指定する例

temp/index.html や dev_pages/ などの開発・一時ファイルをサイトマップから除外したい場合。

python make_sitemap_from_path.py . sitemap.html --exclude "temp/" "dev_pages" "\.bak$"

実行結果の説明: 現在の作業ディレクトリ (.) 以下にあるHTMLファイルを探索し、sitemap.html を生成します。 この際、パスに "temp/" または "dev_pages" を含むディレクトリやファイル、および ".bak" で終わるファイル（例: archive.html.bak）はサイトマップから除外されます。デフォルトの _vti_cnf も引き続き除外されます。

4. 除外パターンを複数指定し、出力ファイルも変更する例

python make_sitemap_from_path.py docs documentation_map.html --exclude "node_modules" "assets" "private/"

実行結果の説明: docs ディレクトリ以下を検索対象とし、documentation_map.html という名前でサイトマップを生成します。 このサイトマップには、パスに "node_modules"、"assets"、または "private/" を含むファイルやディレクトリは含まれません。