Qiita Teams that are logged in
You are not logged in to any team

Log in to Qiita Team
Community
OrganizationAdvent CalendarQiitadon (β)
Service
Qiita JobsQiita ZineQiita Blog
11
Help us understand the problem. What is going on with this article?
@h1romas4

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

More than 1 year has passed since last update.

はじめに

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

謝辞

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

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

11
Help us understand the problem. What is going on with this article?
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
h1romas4
http://another.maple4ever.net

Comments

No comments
Sign up for free and join this conversation.
Sign Up
If you already have a Qiita account Login
11
Help us understand the problem. What is going on with this article?