EurekaMoments

This is my studying logs about Autonomous driving, Machine learning technologies and etc.

MarkdownとPlantUMLでソフトウェアの仕様書や設計書を書くための環境構築手順

背景・目的

自分はこれまでソフトウェア開発において仕様書や設計書を作成する際、Enterprise ArchitectというGUIで操作するソフトウェア設計支援ツールを用いてUML図を描いてきました。
必要なコンポーネントをドラッグアンドドロップするだけでUML図を作成できるので簡単なのですが、図のレイアウトは自分の手で微調整しなければならないので少々面倒です。また、それらの図を挿入する先のドキュメント本体はWordやExcelで作成するのですが、ドキュメント本体もUML図も同じ環境で一度に作成する方法はないかと思っていました。
今回いろいろ調べたところ、自分が愛用するエディタであるVisual Studio Codeであれば、Markdownでドキュメントを書くのとUML図の作成を一度にできるということを知ったので、その方法についてメモしておこうと思います。

実践UML 第3版 オブジェクト指向分析設計と反復型開発入門

実践UML 第3版 オブジェクト指向分析設計と反復型開発入門

  • 作者: クレーグ・ラーマン,依田智夫,今野睦,依田光江
  • 出版社/メーカー: ピアソンエデュケーション
  • 発売日: 2007/11/12
  • メディア: 単行本(ソフトカバー)
  • 購入: 8人 クリック: 179回
  • この商品を含むブログ (29件) を見る

Markdownで書くメリット

自分が思うMarkdown記法のメリットは以下の通りです。

  • 段落など見た目が統一される。コピペした際にも崩れない。
  • プログラムのソースコードを見やすく記載できる
  • テキスト形式なので、GitやSVNのバージョン管理や差分確認、マージがしやすい。
  • テキスト形式なので、各種プログラムによる処理や自動化に馴染みやすい。

Markdown記法一覧

Markdownの各種記法についてはこちらの記事で分かりやすく紹介されているので参照ください。

qiita.com

www.milkmemo.com

環境構築手順

1. Visual Studio Codeをインストールする

まずはエディタとしてVisual Studio Codeをインストールします。
こちらのサイトからインストーラをダウンロードして実行すればOKです。
Visual Studio Code

2. PlantUMLをインストールする

Visual Studio Codeの拡張機能であるPlantUMLをインストールします。
PlantUMLで検索すれば以下のものが見つかるので、これをインストールして再読み込みで有効にします。
f:id:sy4310:20181217065800p:plain

3. Javaをインストールする

PlantUMLを実行するにはJavaの実行環境が必要になります。
そのため、下記の手順でJavaを予めダウンロード、インストールしておきます。

  1. Javaのダウンロードサイトを開く。
  2. 「無料Javaのダウンロード」ボタンを押す。
  3. 「同意して無料ダウンロードを開始」ボタンを押す。
  4. ダウンロードしたインストーラを実行してインストールします。自分のPCはWindows10 64bit版なので、「jre-8u191-windows-x64.exe」がインストーラになります。

4. Graphvizをインストールする

PlantUMLがUML図を描画するために使用しているソフトウェアであるGraphvizをインストールします。下記の手順でインストーラをダウンロードしてインストールします。

  1. Graphvizのダウンロードサイトを開く。
  2. 上部のメニューから「Download」を選択して開く。
  3. 自分のPCのOSに合わせて、ダウンロードするインストーラを選ぶ。自分のPCはWindowsなので、Windowsのカテゴリにある「Stable 2.38 Windows install packages」を選ぶ。
  4. 「graphviz-2.38.msi」を選んでダウンロードして実行すればOK。

5. Markdown Preview Enhancedをインストールする

Visual Studio Codeの拡張機能であるMarkdown Preview Enhancedをインストールします。
検索すれば下記のものが見つかるので、インストール、再読み込みで有効にします。
f:id:sy4310:20181217075451p:plain この機能をインストールすることで、Visual Studio Code上で編集するMarkdown記法のテキストファイルにPlantUMLのコードを直接記述できるようになり、共通の環境下で文章を書く + UML図の描画をできるようになります。

環境構築後の動作確認

動作確認として、適当なUMLドキュメントを作成してみました。今回構築した環境で実際に編集しているときの様子は以下のようになります。 f:id:sy4310:20181217084750p:plain

拡張子を.mdにしてMarkdown記法のテキストファイルを作成して、Visual Studio Codeで開きます。その際に、コマンドで「Ctrl + k v」を押せばPreview画面が表示されます。

ファイル上でPlantUMLのコードを書く際は下記のようにします。
f:id:sy4310:20181217090234p:plain
これにより、コード部分はPlantUMLによるUML図だと認識され、Preview画面にはUML図が下記のように表示されます。
f:id:sy4310:20181217090542p:plain

Markdownでドキュメントを書く際に便利な拡張機能

Visual Studio CodeでMarkdownのドキュメントを作成する際は下記のような拡張機能があり便利なので、一緒にインストールしておくといいと思います。

1. Paste Image

コマンド「Ctrl + Alt + v」で、クリップボードにコピーした画像を直接コピペできます。この時ペーストされた画像は、そのMarkdownファイルと同じディレクトリに、「YYYY-MM-DD-hh-mm-ss.png」の形式で保存されます。

2. markdown-index

Markdownの#や##で書くような各見出しに自動で番号を割り振ってくれる機能です。コマンド「Ctrl + p」でコマンドパレットを開き「>addindex」と入力すると、コマンド候補に「Markdown add index」と表示されるのでそれを実行します。

作成したドキュメントをHTMLやPDFに変換する

Markdownで作成したドキュメントは、最終的にはPDFやHTML形式に変換して配布することになります。今回構築した環境においては、下記の手順で行うのが一番シンプルだと思います。

  1. Markdown Preview EnhancedのPreview画面上で右クリック。
  2. 開いたメニューから「Open in Browser」を選択する。
  3. 使用しているWebブラウザ上でファイルが表示される。
  4. 印刷メニューからPDF変換を実行して保存する。

以上の手順で変換したPDFファイルは下記のようになり、各種PDFリーダーで閲覧できるようになります。

f:id:sy4310:20181217120551p:plain

今回参考にさせていただいた記事

cpp-learning.com

qiita.com

qiita.com

qiita.com

Visual Studio Code | ビットウィンのスタッフブログ