前回に引き続き、OutSystems用ドキュメント自動生成ツール、ForgeのOutDocの話題です。
そのままだとどの用途にも今一使いづらいOutDocなので、少しずつカスタマイズ方法を確認して見たいと思います。
目次
OutDoc
今回のゴール
自動で生成されるドキュメントから、不要な節を削除する手順を確認してみます。
テストなので、どの節でもいいのですが、今回はやりやすいように最後にある「3.10 Themes」を消します。
これができれば、自動生成されるドキュメントの一部だけを利用したいときに、見るべき項目だけを出力するシンプルなドキュメントを出すようになります。
実施前のこの目次が
最後の節が消えてこんな風に
本文の最後にあった3.10 Themesの表が
丸ごと消えてこんな風になります。
現状仕様の調査
「3.10節を削除する」という要求を満たすため、まずはOutDocの現状を調査して、改修方法を検討しましょう。
OutDocを構成する部品をざっと眺めていると、Logicタブに節の名前らしきものを含むActionがあります。
名前からして、このActionで3.10節部分を生成していそうなので、まずはこのActionを使っている部分を検索。
Actionそのものと、Web Block1つ(2つのプロパティでこのActionを見ている)が見つかりました。
検索結果をダブルクリックして確認してみると「DesignDocument」というWeb BlockでドキュメントHTMLの生成を行っています。
また、そのWeb Blockにさらに「Section_1_Implementation」「Section_2_Implementation」「Section_3_Implementation」というWeb Blockを配置して各章の表示を担っているようです。目標は3.10の非表示なので、「Section_3_Implementation」から3.10を表示する部分を削除するとともに、「Section_1_Implementation」が目次なので、そこからも該当部分を削除する必要があります。
また、このWeb Blockの2つの(検索したActionを参照している)プロパティは必須(Is Mandatory=YES)になっています。
必須のプロパティは置いておくとエラーになるので削除しましょう。
修正方針
以上をまとめると
- 「Section_1_Implementation」Web Block(目次)から3.10表示部分を削除する
- 「Section_3_Implementation」Web Block(ドキュメント3章)から3.10表示部分を削除する
- 上記2つのWeb Blockを含む「DesignDocument」入力パラメータから3.10関係の2つを削除
- 「Section_3_10_GenerateThemes」Actionの呼び出しが無駄なので削除
という方針になります。
修正手順
オリジナルのOutDocを変更したくないのでCloneでコピーします。
コピーしたモジュールはIndependent ModulesのCloneOfOutDocモジュールになります。
まずは目次を削除します。
「Section_1_Implementation」の3.10/3.10.1それぞれContainerごと削除。
「Section_3_Implementation」はさらにSection_3_10_ThemesというBlockを配置しているので、「Section_3_Implementation」からそのBlockをContainerごと削除。
「Section_3_Implementation」の入力パラメータ「ThemesList」「ReferencedThemeList」を削除します。
最後に、利用している部品を削除したために不要となった、DesignComponentのPreparation Actionから下記の「Section_3_10_GenerateThemes」Action呼び出しを消しておきます。
置いといても実害はないでしょうが無駄なので。
この状態でパブリッシュして、ブラウザで開き、適当なアプリケーションのドキュメントを開くと、ゴールの狙い通りの表示になっています。
今後の展望
OutDocのカスタマイズが実際に可能であることが明らかになりました。
これでプロジェクトの開発プロセスで必要なドキュメントを定義する際、自動生成で対応可能な部分(だけ)をOutDocで生成することができます。
また、OutDocはバージョン指定もできず、OutSystems環境で表示するしかないので、一定タイミングで自動でドキュメントを生成するとともに、過去バージョンを差分比較できる形式でアップロードなりメール送信なりするようにしておくと便利かもしれません。