Help us understand the problem. What is going on with this article?

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

はじめに

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

こんな時に:

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

Screenshot from 2020-04-09 12-08-56.png

Screenshot from 2020-04-09 12-39-54.png

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

変換用ビルドスクリプト

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 の編集が可能です。

Screenshot from 2020-04-09 10-49-05.png

Gitpod 対応

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

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

Open in Gitpod

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

Screenshot from 2020-04-09 11-06-49.png

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

2020-04-09_14-56.png

なお 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'
}

謝辞

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

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

h1romas4
http://another.maple4ever.net
https://twitter.com/h1romas4
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした