check_module_name.ps1 技術ドキュメント

プログラムの動作

check_module_name.ps1 は、Sphinxドキュメントプロジェクトの構造と命名規則の健全性をチェックするために設計されたPowerShellスクリプトです。主に以下の3つの側面からドキュメントファイルを検査します。

  1. Indexファイルの命名規則と存在確認:

    • source\cms ディレクトリ以下に存在する *_index.rst または *_index.md ファイルの命名規則をチェックします。特に、ファイル名にハイフン (-) またはアンダースコア (_) が混在している、あるいは不適切な命名がされていないかを確認し、想定外のファイル混入を検出します。

  2. 古いハイフン命名の参照チェック:

    • source ディレクトリ以下の .rst および .md ファイル内で、以前使用されていた可能性のあるハイフン形式の参照文字列（例: N-integration-metal, smoothing-fft）が toctree ディレクティブ内などに残っていないかを検出します。これは、Sphinxのビルド時に multiple toctrees warning などの警告が発生する原因を特定するのに役立ちます。

  3. toctreeでの拡張子明記チェック:

    • source ディレクトリ以下の .rst および .md ファイル内で、toctree ディレクティブのエントリでファイル拡張子（.rst や .md）が誤って記述されていないかを検出します。Sphinxの toctree では通常、拡張子を含めずにファイル名を指定するため、このような記述はエラーや警告の原因となることがあります。

このスクリプトを実行することで、ドキュメントの整合性を維持し、ビルドエラーや警告を未然に防ぎ、効率的なドキュメント管理を支援します。

原理

このスクリプトは、PowerShellの標準コマンドレットと正規表現を組み合わせてドキュメントファイルをスキャンします。

  1. Indexファイルチェック:

    • Get-ChildItem source\cms -Recurse: source\cms ディレクトリとそのすべてのサブディレクトリ内のファイルとディレクトリを再帰的に取得します。

    • Where-Object { $_.Name -match '[-_].*_index\.(rst|md)$' }: 取得したオブジェクトの中から、Name プロパティ（ファイル名）が正規表現パターン [-_].*_index\.(rst|md)$ にマッチするものをフィルタリングします。この正規表現は、ファイル名がハイフンまたはアンダースコアで始まり、その後に任意の文字が続き、最終的に _index.rst または _index.md で終わるファイルを検出します。

    • Select-Object FullName: フィルタリングされたファイルのフルパスのみを選択して表示します。

  2. 古いハイフン命名の参照チェック:

    • Get-ChildItem source -Recurse -Include *.rst, *.md: source ディレクトリ以下にあるすべての .rst および .md ファイルを再帰的に取得します。

    • Select-String -Pattern "N-integration-metal|smoothing-fft": 取得したファイルの内容を検索し、正規表現パターン "N-integration-metal|smoothing-fft" にマッチする行を検出して表示します。これは、N-integration-metal または smoothing-fft のいずれかの文字列が含まれる行を検索します。

  3. toctreeでの拡張子明記チェック:

    • Get-ChildItem source -Recurse -Include *.rst, *.md: source ディレクトリ以下にあるすべての .rst および .md ファイルを再帰的に取得します。

    • Select-String -Pattern "\.rst>": 取得したファイルの内容を検索し、正規表現パターン "\.rst>" にマッチする行を検出して表示します。これは、.rst の後に > が続く文字列が含まれる行（例: .. toctree:: のエントリで module.rst> のように拡張子が誤って指定されているケース）を検出します。

Write-Host コマンドレットは、各チェックセクションのタイトルと終了メッセージをコンソールに出力するために使用されます。

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

このスクリプトはPowerShellの標準コマンドレットのみを使用しており、追加の非標準ライブラリやモジュールのインストールは不要です。

補足: スクリプト実行ポリシーについて PowerShellでは、スクリプトの実行をセキュリティ上の理由から制限している場合があります。スクリプトが実行できない場合は、以下のコマンドをPowerShellコンソールで実行して、現在のユーザーの実行ポリシーを変更する必要があるかもしれません。

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

このコマンドは、インターネットからダウンロードしたスクリプトには署名が必要だが、ローカルで作成したスクリプトは実行できるようにするポリシーを設定します。

必要な入力ファイル

このスクリプトは、検査対象のSphinxドキュメントプロジェクトのファイル群を必要とします。具体的には、スクリプトが実行されるディレクトリの相対パスにある source ディレクトリ内に以下のファイルが存在することを想定しています。

  • source/cms/ ディレクトリ以下に存在する .rst または .md 形式のインデックスファイル（例: my_module_index.rst, another-doc_index.md）。

  • source/ ディレクトリ以下に存在する、すべての .rst および .md 形式のドキュメントファイル。これらは toctree ディレクティブや参照文字列を含んでいる可能性があります。

ファイルの内容は、SphinxのreStructuredText (reST) 形式またはMarkdown形式で記述されている必要があります。

生成される出力ファイル

check_module_name.ps1 スクリプトは、いかなるファイルも生成しません。 すべての検査結果は、スクリプトを実行したPowerShellコンソール（標準出力）にテキスト形式で直接表示されます。

出力される情報は以下の通りです。

  • === Index files check === セクション: 命名規則に問題がある、または特定のパターンに合致するインデックスファイルのフルパスのリスト。

  • === Old hyphen-style reference check === セクション: 古いハイフン形式の参照文字列（例: N-integration-metal）を含むファイルの行情報（ファイル名、行番号、行内容）。

  • === .rst extension usage check === セクション: toctree 内などで .rst> のような拡張子を誤って記述しているファイルの行情報（ファイル名、行番号、行内容）。

  • Check completed. メッセージ: スクリプトの実行完了を示すメッセージ。

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

check_module_name.ps1 スクリプトは、PowerShellコンソールから直接実行できます。スクリプトがあるディレクトリに移動し、以下のコマンドを実行します。

.\check_module_name.ps1

注意点:

  • スクリプトが配置されているディレクトリに移動して実行するか、スクリプトへのフルパスを指定してください。

  • PowerShellの実行ポリシーによっては、スクリプトの実行がブロックされる場合があります。その際は、「必要な非標準ライブラリとインストール方法」セクションに記載されている Set-ExecutionPolicy コマンドを参照し、適切なポリシーを設定してください。

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

以下の例は、check_module_name.ps1 を実行した場合の標準出力の形式を示しています。実際の出力は、検査対象のドキュメントプロジェクトのファイル構造と内容によって異なります。

実行コマンド:

.\check_module_name.ps1

想定される出力例:

=== Index files check ===
C:\Users\username\Documents\myproject\source\cms\bad-file_index.rst
C:\Users\username\Documents\myproject\source\cms\another_wrong-index.md

=== Old hyphen-style reference check ===
C:\Users\username\Documents\myproject\source\module_a.rst:15:   :toctree: N-integration-metal
C:\Users\username\Documents\myproject\source\module_b.md:20: - [Link](smoothing-fft.md)

=== .rst extension usage check ===
C:\Users\username\Documents\myproject\source\parent_doc.rst:10:   :toctree:
C:\Users\username\Documents\myproject\source\parent_doc.rst:11:     child_doc.rst>
C:\Users\username\Documents\myproject\source\section_intro.md:5: - [Sub Module](sub_module.md>)

Check completed.

この出力例では、

  • Index files check セクションで、命名規則に問題がある可能性のある bad-file_index.rst と another_wrong-index.md が検出されています。

  • Old hyphen-style reference check セクションで、module_a.rst の15行目と module_b.md の20行目に古いハイフン形式の参照が見つかっています。

  • .rst extension usage check セクションで、parent_doc.rst の11行目と section_intro.md の5行目に、toctree エントリで誤って拡張子を含んでいる箇所が検出されています。

この情報を基に、ドキュメントファイルの修正を行うことができます。