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に出力した日時を出力するので、内部事情が見えるのが気持ち悪かったのでコントロールできるようにしました。
ただし、後述のフッターの日付を変更する(おまけ)
で書いている内容をした場合は、ここで書いた内容は無くていいです。
- 最後に、後片付けをします。
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'] = ''
こうして、フッターにコピーライトが出るようになりました。
おわりに
コピーライトの出力部分がほんと無理やりですね。