AsciidoctorとGradleでつくる文書執筆環境 v2

13617 ワード
Gitpod asciidoc asciidoctor gradle gradle テキストリンク

はじめに

asciidoctor-gradle-pluginを活用して Asciidoc 形式の文書を Gradle を使って簡単に HTML/PDF 文書に変換できるビルドテンプレートをつくってみました。

こんな時に:

  • ビルド依存が「Java 8 以上が導入されていること」のみであることから、多くの Java ソフトウェア開発現場のドキュメント作成に。
  • クラウド IDE の Gitpod に対応。ブラウザーさえあればどこでも、プレビューしながらの Asciidoc 文書の執筆・ビルドが可能。薄い技術書の執筆に。

この記事がみ​な​さ​ん​の​執​筆​活​動​の​お​手​伝​い​に​な​れ​ば​幸​い​で​す。

変換用ビルドスクリプト

asciidoctor-gradle-plugin v3.1.0 用の build.gradle を次の github リポジトリーに変換サンプル Asciidoc 文書とともに公開しています。

https://github.com/h1romas4/asciidoctor-gradle-template

AsciidoctorとGradleでつくる文書執筆環境

リポジトリーごと Download ZIP 後、./gradlew docs もしくは .\gradlew.bat docs すると src/docs/asciidoc/ 配下に含まれている文書が HTML/PDF に変換されます。

本リポジトリーにはフォントや CSS スタイル・PDF テーマ、Asciidoctor 日本語特有の不具合のパッチなどが含まれていますので Java 8 以降が入っている環境であればすぐにビルドできると思います。

変換後の文書サンプル

「AsciidoctorとGradleでつくる文書執筆環境」リポジトリー自体の使い方を書いた文書がサンプル文書となっています。詳しいビルドの仕方やカスタマイズ方法は次を参照ください。クライアントがウェブプロキシー配下に置かれている環境の場合の手順も入っています。

AsciidoctorとGradleでつくる文書執筆環境(HTML version)

AsciidoctorとGradleでつくる文書執筆環境(PDF version)

またリポジトリーでは、Visual Studio Code を使った執筆を想定していくつかのワークスペース設定（.vscode/）を事前に含めており、vscode 上でプレビューしながら Asciidoc の編集が可能です。

Gitpod 対応

クラウド IDE である Gitpod 向けに、リポジトリーには .gitpod.yaml が含まれています。

次のボタンを押すと Gitpod 上でビルドが走り（初回は 3分程度）、ローカルビルド環境の準備なしにブラウザー上で執筆ができます。画像ファイルなどはブラウザーにドラッグアンドドロップでアップロードすることができます。

本格的に使う場合は、ご自身の github アカウントにリポジトリーをコピーするなどしてお使いください。github の Use this template ボタンが便利です。

Asciidoc プレビューを行う場合は、次の外側のアイコンをクリックしてください。プレビューは asciidoctor-vscode プラグインで行っていますが、Gitpod のインターナル Asciidoc サポートも同時に有効になっているため２つアイコンがでてしまうようです。

なお 2020/4 現在、Gitpod の無料枠はオープンリポジトリー（OSS）で 50時間/月(Usage 上は100時間 remain になっている?) までの利用となっており、git push 前の修正ファイルの維持はラストアクセスから 14日間となっているようです。 → Life of a Workspace

asciidoctor-gradle-plugin について

Asciidoctor Gradle Plugin Suiteは Gradle から AsciidoctorJ を簡潔な DSL で呼び出すためのプラグインです。

準備したリポジトリーの build.gradle（本記事用にコメントを追加） は次のようになっています。修正する場合や、新規作成する場合の参考になれば。ドキュメントと見比べると分かりやすいと思います。

plugins {
    // 利用する asciidoctor-gradle プラグインを宣言
    id 'org.asciidoctor.jvm.convert' version '3.1.0'
    id 'org.asciidoctor.jvm.pdf' version '3.1.0'
    id 'org.asciidoctor.jvm.gems' version '3.1.0' // Ruby gem プロキシープラグイン
}

repositories {
    mavenCentral()
    // Asciidoctor 用の追加 gem をプロキシーするための
    // org.asciidoctor.jvm.gems プラグイン用の宣言
    ruby.gems()
}

dependencies {
    // ローカル Ruby gem を追加（diagram SVG 用のフォントパッチ）
    asciidoctorGems files('gradle/repos/gem/prawn_svg_font_patch-0.1.0.gem')
    // リモート Ruby gem を追加（日本語禁則処理）
    asciidoctorGems 'rubygems:asciidoctor-pdf-linewrap-ja:0.7.0'
}

// HTML 変換用定義
asciidoctor {
    // 必要な Ruby gem をビルド前に配置するための dependsOn
    dependsOn asciidoctorGemsPrepare
    baseDir file('src/docs/asciidoc')
    sources {
        include 'index.adoc'
    }
    // 画像リソースを定義（build/ にコピーされる）
    resources {
        from('src/docs/asciidoc') {
            include 'Chapter*/images/*'
        }
    }
    // CSS を指定（.html の先頭に追記される）
    asciidoctorj {
        attributes 'stylesdir': '@style',
            'stylesheet': 'asciidoctor.css'
    }
}

// PDF 変換用定義
asciidoctorPdf {
    // 必要な Ruby gem をビルド前に配置するための dependsOn
    dependsOn asciidoctorGemsPrepare
    baseDir file('src/docs/asciidoc')
    // PDF 用のフォント定義
    fontsDir file('src/docs/asciidoc/@font')
    sources {
        include 'index.adoc'
    }
    // PDF テーマを指定
    asciidoctorj {
        attributes 'pdf-stylesdir': "@style",
            'pdf-style': 'pdf'
    }
}

// AscidoctorJ の設定定義
asciidoctorj {
    // 利用モジュール
    modules {
        // asciidoc-diagram - PlantUML 利用
        diagram.use()
        diagram.version '1.5.16'
        pdf.version '1.5.3'
    }
    // JRuby Asciidoctor 呼び出し時の -r 指定
    requires = [
        'asciidoctor-diagram',
        'asciidoctor-pdf-linewrap-ja',
        'prawn_svg_font_patch'
    ]
    attributes 'source-highlighter': 'coderay'
}

謝辞

本​文​書​の​手​順​の​実​装​で​あ​る​ビ​ル​ド​ス​ク​リ​プ​ト​や​テー​マ​で​は​次​の​プ​ロ​ダ​ク​ト​と​技​術​資​料​が​使​わ​れ​て​い​ま​す。

素​晴​ら​し​い​成​果​を​公​開​さ​れ​て​い​る​み​な​さ​ま​に​感​謝​し​ま​す。