はじめに
設計書を作成する際のツールとしてAsciidoctor（adoc） を紹介します。
私もAsciidoctorを設計書作成の際に利用しています。
Asciidoctorはドキュメントの構造化や見た目のカスタマイズが非常に簡単です。
この記事では、Docker を利用して手軽に環境をセットアップし、Asciidoctorの基本的な使い方と設計書作成で役立つ機能、さらにはHTMLやPDFへの変換までを解説します。
完成イメージ
Asciidoctorとは？
はじめに、「Asciidoctorはなんぞや！」ということで、説明します。
Asciidoctorは、軽量なマークアップ言語である AsciiDoc の一つです。設計書、仕様書、ブログ記事、チュートリアルなどの技術文書を作成する際に便利で、Markdownに似たシンプルな書式でより高度なフォーマットが簡単に利用できます。
ベンチャー企業で上司から「設計書作っといて！」と条件なしに丸投げされた際には、Asciidoctorを利用すると便利かも知れません。
では、さっそく始めていきます。
Dockerを使ったAsciidoctor環境の構築
まず、Dockerを使ってAsciidoctorの環境を構築します。Dockerを使うことで、ローカル環境を汚すことなく、すぐにAsciidoctorを使い始めることができます。
Dockerがまだインストールされていない場合
Dockerをインストールしていない方は、以下の手順に従ってインストールしてください。
1. Dockerのインストール
Dockerをインストールするには、公式サイトからインストーラーをダウンロードして実行します
Docker Desktop ダウンロードページ
自分のOS（Windows、macOS、Linux）に対応するバージョンを選び、インストールファイルをダウンロードします。
ダウンロードしたインストーラーを実行し、指示に従ってインストールします。
2. インストール確認
インストールが完了したら、ターミナルやコマンドプロンプトを開き、次のコマンドを実行してDockerが正しくインストールされたか確認します。
% docker --version
Docker version 24.0.7, build afdd53b
これにより、インストールされたDockerのバージョンが表示されればインストールは完了です。
Dockerインストール後
1. Dockerイメージの準備
Asciidoctorの公式Dockerイメージを使用します。
以下のコマンドを実行することで、Dockerイメージを取得します。
% docker pull asciidoctor/docker-asciidoctor
2. プロジェクトディレクトリの作成
次に、プロジェクトディレクトリを作成し、その中に書きたい .adoc ファイルを作成します。
% mkdir asciidoc_project
% cd asciidoc_project
% touch sample.adoc
これでasciidoc_projectフォルダ内にsample.adocが格納されていればOKです。
3. ファイル内に簡単な文書を記述
作成した sample.adocに、簡単な文書を記述します。
= Asciidoctor サンプル
:doctype: article
:date: 20xx-xx-xx
:toc: left
:toclevels: 2
== はじめに
これはAsciidoctorのサンプルです。
== セクション
ここに本文を記述します。
=== サブセクション
さらに詳細な内容を書くことができます。
4. AsciidoctorでHTMLを生成
Dockerを使って、sample.adoc をHTMLファイルに変換します。以下のコマンドを実行してください。
% docker run --rm -v $(pwd):/documents asciidoctor/docker-asciidoctor asciidoctor sample.adoc
上記のコマンドを実行すると、同じディレクトリに sample.html が生成されます。
5. HTMLファイルを確認
生成された sample.html ファイルをブラウザで開きます。
以下のように表示されていればOKです。
（:toc: left_を記述したことで、左側に目次が追加されました。ここから各トピックに飛べます。）
これで、簡単にAsciidoctorでドキュメントを作成し、HTMLに変換できました！
ここからはAsciidoctorの基本的な書き方について話します。
Asciidoctorの基本的な書き方
見出し
Asciidoctorでは、見出しは等号（=）で記述します。等号の数が増えるほど、見出しの階層が下がります。
= 見出し1
== 見出し2
=== 見出し3
リストの作成
順序付きリストや順序なしリストも簡単に作成できます。以下のように記述します。
* 順序なしリストのアイテム
. 順序付きリストのアイテム
テキストの装飾
テキストを太字にしたり、斜体にしたり、コードを挿入するのも簡単です。
*斜体*
**太字**
`インラインコード`
リンクと画像の挿入
リンクや画像もシンプルに挿入可能です。リンクのテキストや画像のキャプションも簡単に設定できます。
link:https://qiita.com/[Qiitaへのリンク]
image::example.jpg[これはサンプル画像です]
設計書作成での具体的な活用
基本的な書き方は抑えたので、ここからは細かい書き方について記載します。
表の作成
表を使った要件の整理や、項目間の関係を視覚的に表現することができます。設計書では、要件定義や機能一覧を表で管理するケースが多いので、Asciidoctorの表機能を使うと便利です。
Asciidoctorは、表は次のように記述します。
|=== で表の開始と終了を表し、セルは | で区切ります。
|===
|機能 |説明 |優先度
|ログイン |ユーザー認証 |高
|データ検索 |ユーザーがデータを検索できる |中
|===
この書き方で、シンプルな表が作成できます。
HTMLやPDFへの変換
作成したAsciidoctorファイルを簡単にHTMLやPDFに変換できます。特に設計書をPDF形式で納品する場合にも便利です。
HTMLの生成
以下のコマンドで.adocファイルをHTML形式に変換します。
asciidoctor <adocファイル名>
(例)
asciidoctor sample.adoc
PDFの生成
PDFとして出力したい場合は、asciidoctor-pdfをインストールし、以下のコマンドを実行します。
gem install asciidoctor-pdf
asciidoctor-pdf yourfile.adoc
高度な機能
コードブロックの挿入
プログラムコードをドキュメントに含める場合、シンタックスハイライト付きで表示することができます。例えば、adocの設定を加え、Pythonコードを次のように書きます。
.adoc ファイルの冒頭に以下の行を追加して、ハイライトを指定します。
:source-highlighter: coderay
* 「｀」は半角の「`」に直して利用してください。
｀｀｀
def hello():
print("こんにちは、世界！")
｀｀｀
ブラウザで確認すると↓こんな感じで表示されます。
図の作成
システム構成図
== システム構成図
[plantuml, format="svg"]
----
package "Webアプリケーション" {
[ブラウザ] --> [Webサーバー] : リクエスト
[Webサーバー] --> [アプリケーションサーバー] : APIコール
[アプリケーションサーバー] --> [データベース] : データの読み書き
}
package "外部サービス" {
[アプリケーションサーバー] --> [認証サービス] : 認証要求
[認証サービス] --> [アプリケーションサーバー] : 認証トークン
}
----
認証フロー
== 認証フロー
ユーザーがログインすると、アプリケーションサーバーを通じて外部の認証サービスに認証要求を送信し、認証トークンを取得します。このトークンを使用して、セッションが維持されます。
[plantuml, format="svg"]
----
group テナントの認証
クライアント -> アプリケーションサーバー : 認証リクエスト
アプリケーションサーバー -> 認証サービス : 認証情報
認証サービス --> アプリケーションサーバー : 認証トークン
アプリケーションサーバー --> クライアント : 認証トークン
end
----
データベース設計
== データベース設計
### テーブル一覧
|===
|テーブル名 |説明 |カラム
|users
|ユーザー情報を管理
|id, username, email, password_hash, role
|items
|ユーザーが登録したデータ
|id, user_id, item_name, item_description, created_at, updated_at
|===
### ER図
[plantuml, format="svg"]
----
entity "users" {
* id : INT
* username : VARCHAR
* email : VARCHAR
* password_hash : VARCHAR
* role : VARCHAR
}
entity "items" {
* id : INT
* user_id : INT
* item_name : VARCHAR
* item_description : TEXT
* created_at : DATETIME
* updated_at : DATETIME
}
users ||--o{ items : "user_id"
----
こんな感じで図も作成できます！！！
最後に
今回は、Asciidoctorの基本的な使い方と設計書作成で役立つ機能を説明しました。Asciidoctorを活用することで、ドキュメントや設計書を効率的かつ美しく作成できるようになります。是非この機会に試してみてください！
今回紹介したはAsciidoctorの機能はまだほんの一部です。
さらに詳しく知りたい方は、Asciidoctorの公式ドキュメントを覗いてみてください。
https://asciidoctor.org/docs/