Asciidoctor実行バッチ

7801 ワード
asciidoc asciidoctor asciidoctor テキストリンク

AsciiDocドキュメントのリポジトリ構成で書いていたプチツールに関する内容です。

ツール実行により出来上がるHTML

ツール資材について

資材は、下記に置いています。
動作の確認をしている環境条件としては、Windows10でAsciidoctorがインストール済みであることです。

このうち対象となる資材はこちら。

  • document-confirm.bat
  • document-release.bat
  • bat/jp配下

ツールが必要となる場面

GitHub Flowをベースに以下のような作業の流れで考えたときのfeature/workerの赤枠の部分で、ツールを使用します。

confirm and fix

作業者が、自分が書いた内容を確認するために、ツールを使用して自端末にHTMLを出力します。
公開する形式と同じ状態で出力して確認することができます。

ツールは以下を実行します。

  • document-confirm.bat （HTMLの出力先 : document-confirmフォルダ）

output HTML

ここでは完成したドキュメントをHTML出力します。責任者が取りまとめをおこなうイメージです。

ツールは以下を実行します。

  • document-release.bat （HTMLの出力先 : document-releaseフォルダ）

ツールの詳細説明

2つのバッチの実行内容はほぼ同じになっていますので、document-confirm.batの内容をもとに処理の流れを追って説明します。

  • Asciidoctorの引数として与える値を定義
rem defined
SET REVNUM='revnumber=0.0.1'
SET STYLE='stylesheet=..\..\css\asciidoctor-custom.css'
  • favicon、JavaScriptなどのHTMLヘッダーに独自のタグを追加するため、docinfo.htmlを各フォルダにコピー

※docinfo.htmlの説明は、HTMLヘッダーに独自コンテンツを追加 をご参照ください。

rem include favicon
copy bat\head\index\docinfo.html %LANG_MODE%\index\
copy bat\head\docinfo.html %LANG_MODE%\change_log\
copy bat\head\docinfo.html %LANG_MODE%\reference\
copy bat\head\docinfo.html %LANG_MODE%\tutorial\
  • 先ほどのfavicon画像やJavaScriptファイルをコピー
rem images,js
xcopy /Y /E %LANG_MODE%\images %EXEC_MODE%\%LANG_MODE%\images\
xcopy /Y /E %LANG_MODE%\js %EXEC_MODE%\%LANG_MODE%\js\
  • 大項目ごとに作成したバッチを実行

こうすることで変換処理が並走するので、ちょっと早くなります。
ドキュメント量が多くなってきたときの対処としてこのようにしています。

start bat\%LANG_MODE%\tutorial.bat
start bat\%LANG_MODE%\index.bat
start bat\%LANG_MODE%\change_log.bat
start bat\%LANG_MODE%\reference.bat

どのファイルも同じ処理なので、代表してbat\jp\reference.batに移動します。

  • Asciidoctorのコマンドを実行
SET TARGET=reference
call asciidoctor -a %REVNUM% -a %STYLE% -a "doctime=" %LANG_MODE%\%TARGET%\*.adoc

変数をバラシつつ解説をいれます。

まず、オプションを外すと以下のようになります。
フォルダ配下の拡張子が.adocのファイルを読み込み、HTMLに出力します。

call asciidoctor jp\reference\*.adoc

オプションの内容ですが、-aだけ使用しています。 --attributeでもよいです。
name[=value]という書き方で指定します。

-a 'revnumber=0.0.1'
revnumberにはリビジョン番号を入れます。

-a 'stylesheet=....\css\asciidoctor-custom.css'
stylesheetには、HTMLが使用するcssファイルを指定します。
指定することで、HTML自体にcssの内容をすべて詰め込んで出力します。
そのため、HTMLファイル単体でもスタイルが適用された状態となります。

cssファイルを外部ファイルとして読み込みたい場合は、これではなくdocinfo.htmlに書くのがよさそうです（未確認です）。

-a "doctime="
doctimeは、最終更新時間です。空にすることで出ないようにしています。
指定しない場合、HTMLに出力した日時を出力するので、内部事情が見えるのが気持ち悪かったのでコントロールできるようにしました。

  • doctimeの指定をしなかった場合

  • doctimeを指定した場合

ただし、後述のフッターの日付を変更する（おまけ）で書いている内容をした場合は、ここで書いた内容は無くていいです。

  • 最後に、後片付けをします。
start bat\%LANG_MODE%\common.bat
  • common.batの中

まず、最初にコピーしたdocinfo.htmlはドキュメントをHTML化した後は不要になるので削除します。
次に、Asciidoctorコマンドで出力したHTMLはAsciiDocファイルと同じ場所に出力されるので、document-confirmに移動しています。
最後は、画像ファイルなどを単にコピーしています。

del %LANG_MODE%\%TARGET%\docinfo.html
move /Y %LANG_MODE%\%TARGET%\*.html %EXEC_MODE%\%LANG_MODE%\%TARGET%\
xcopy /Y /S /E %LANG_MODE%\%TARGET%\images %EXEC_MODE%\%LANG_MODE%\%TARGET%\images\

フッターの日付を変更する（おまけ）

※ツールの内容からずれるのですが、Asciidoctorのバージョンが変わったことで元々ツールでやっていたのが出来なくなり宙に浮いたためここで記載します。

まず、標準ですと前述の通り、フッターにはAsciiDocファイルの最終更新日付が出力されます。

指定の仕方は簡単で、以下のようにAsciiDocファイル内にAttributeを追加します。

:docdatetime: 2030-04-01

このようにして、ドキュメントの公開日に合わせる運用がよいと考えます。
定数定義ファイルのcommon\base.adocで定義し、全ファイル同じ日付にしています。

  • コピーライト表記に使う

コピーライトを出力するのにちょうどいい場所だったので、私は日付ではなくコピーライトを入れました。

:docdatetime: ©SAMPLE 2030-2040

とってもいま一つなのですが、Asciidoctorのrubyファイルを修正して、Last updated表記を消して実現しています。

C:\Ruby27-x64\lib\ruby\gems\2.7.0\gems\asciidoctor-2.0.10\lib\asciidoctor
document.rb

# attrs['last-update-label'] = 'Last updated'
attrs['last-update-label'] = ''

こうして、フッターにコピーライトが出るようになりました。

おわりに

コピーライトの出力部分がほんと無理やりですね。