ドキュメントの自動化

アビオニクスに関連するプロジェクトに取り組んでいる間、プロジェクトの完全な説明を含むいくつかのドキュメントセットを作成する必要がありました。 また、ESPD、KT-178Bなど、ドキュメントの設計と内容に関する多くのGOSTの要件を考慮する必要がありました。



説明には以下を含める必要があります。

• ソフトウェア開発計画
• ソフトウェア要件
• ソフトウェア要件の実装の説明
• ソフトウェアおよび実装要件のトレーサビリティ（コンプライアンス）テーブル
• ソフトウェアテストの説明（例とソフトウェア検証手順）
• ソフトウェア要件とテストのトレーサビリティ（コンプライアンス）テーブル
• 問題報告
• 構成ポインター（ソフトウェアバージョンの説明とサードパーティのソフトウェアおよびハードウェアとの互換性）

ドキュメントの量は非常に多いです。 すべてのドキュメントのデータは相互に関連しているため、プロジェクトを変更する（たとえば、新しい要件を追加する）場合、ほとんどすべてのドキュメントを編集する必要があります。 さらに、どこかで間違いを犯したり、修正を忘れたりする可能性があり、ドキュメントの誤りにつながります。







記事の後半で、この問題をどのように解決したかを説明します。

ドキュメントジェネレーターアーキテクチャ

そのため、プライマリドキュメント（CSV形式のテーブル、XMLドキュメント）のデータを使用してすべてのドキュメントを作成する自動化ツールを使用することが決定されました。 プロジェクトに変更を加えたら、ドキュメントセットの生成を再開できます。



CSV形式のテーブルは、テーブルプロセッサで簡単に編集できます。 プロジェクトデータ（現在のバージョン、名前、互換性のある機器）はXML形式で保存されていました。



要件の実装の説明は、ソースコードのdoxygenコメントに既に含まれています。 そのような場合専用のDoxygenは、XML形式のドキュメントを生成できます。



ドキュメントジェネレーターは、ドキュメントテンプレートに基づいて、LaTeXドキュメントを作成します。これは既にPDF形式で顧客に転送されています。

ドキュメントジェネレーター

ドキュメントを作成するためのこのようなシステムを実装するには、テンプレート処理ユーティリティとアセンブリスクリプトが必要でした。



Makefileにビルドスクリプトを実装しました。 スクリプトは次のアクションを実行しました。

• ソースを入手しました
• Doxygenを使用して生成されたXML記述
• pytemplate.pyを使用して、テンプレートから必要なすべてのドキュメントを収集しました
• LaTeXによって生成されたPDF
• フォルダーツリーを生成し、記録用のディスクイメージを作成しました
• 必要なサポートドキュメントを作成しました（タイトルページ、ディスクラベル付きのファイル）

システムの重要な要素は、ドキュメントテンプレート処理ユーティリティです。

テンプレート処理ユーティリティ

ソースコードを入手できます： github.com/krotos139/pytemplate



または、次のコマンドを使用してユーティリティをインストールします。

sudo pip install pytemplateproc
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

ユーティリティの使用法：pytemplate.py [オプション]

オプション：

• --versionバージョンを表示する
• -h、--help起動キー情報を表示します
• -t TEMPLATE、--template = TEMPLATEテンプレートファイルへのパスを指定します
• -o OUTPUT、-output = OUTPUT出力ファイルへのパスを指定します
• -f FORMAT、-format = FORMATテンプレートファイルの形式は、値（odtおよびtext）を取ることができます
• -a ARG、-arg = ARGテンプレートの追加エンティティ

テンプレートには、必要な外部ソースのデータである情報が含まれています。 テンプレートの処理中にユーティリティは必要なデータをロードし、データをテンプレートに入力するときにそれを使用します。



サポートされているデータソース：

• CSVテーブル（特定のルールに従って、Exelで編集可能）
• XML文書
• テキストファイル
• SQLiteデータベース
• ファイルからのMD5関数
• ファイルデータ検索機能

テンプレートファイルと生成されたファイルへのパスがユーティリティに転送されます。 データソースへのパスは、すべてテンプレートで定義されており、1つのテンプレートでさまざまなデータソースを使用できるため、プログラムに転送されません。



テンプレートの例：

 {%- set docs = load_csv("database2.csv") %} \subsection{ } \begin{longtable}{|m{2cm}|m{3cm}|m{3cm}|m{3cm}|m{3cm}|} \caption{ } \label{tab:reports}\\\hline {\centering } & {\centering } & {\centering } & {\centering  } & {\centering } \\\hline \endfirsthead \caption*{\it{ } \ref{tab:reports}}\\\hline {\centering } & {\centering } & {\centering } & {\centering  } & {\centering } \\\hline \endhead {%- for item in docs %} {{ item.id }} & {{ item.name }} & {{ item.ref }} & {{ item.sign }} & {{ item.inv }} \\\hline {%- endfor %} \end{longtable} \newpage
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

おわりに

pytemplateユーティリティを使用すると、テンプレートに入力するデータを使用して、テンプレートに関するドキュメントとレポートを作成できます。 さらに、データはスプレッドシートやデータベースに便利な形式で保存できます。