Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(概要)

にほんブログ村

はじめに

Visual Studio Code(VSCode)は、Microsoftが提供している無料で軽量、かつ強力なコードエディタです。

VSCodeは非常に多彩な設定ができることから、ソフトウェア開発を行うにあたっては、ソースコードを書いたりデバックしたりするだけでなく、うまく拡張機能を使えば、ソフトウェアの設計書まで作ることができます。

今回は、VSCodeでMarkdownとUMLを使ってソフトウェア設計書を書けるようにすることを目的とし、最終的にはMicrosoftのWord形式のファイルを生成する方法の概要を紹介します。

ソフトウェア設計書を書くための条件

ソフトウェアの設計書を作成するにあたっては、多くの方がソフトウェアの設計書をWordやExcelなどを使用して作成していると思います。

これらのオフィスツールは、文章や図を書くには非常に有用で、リッチな書式や図表による表現が可能です。

しかしながら、複数人で設計書を書こうとすると、どうしても差分やマージや履歴の管理など、細やかな変更管理が必要となりますが、現状、これらのオフィスツールは、こういった管理がイマイチなところがあります。

一方でソフトウェアのソースコードは、GitHubやGitLabなどを活用すれば、差分やマージや履歴が細かく管理できます。

そこで今回は、リッチな書式や図表による表現の優先度を低くし、テキストだけでソフトウェアの設計書を書けるような環境を作っていきます。

テキストだけでソフトウェア設計書を書くための条件は以下の通りです。

・テキストのみで書くため、リッチな書式は使わない

・図面をコードで書く

・開発環境と同じ環境で設計書を書く

・完成した設計書はWord形式で出力する

・作成したテキスト(コード)は、Gitで管理する

上記のような条件でソフトウェアの設計書を作成するために、ここでは、冒頭にも述べた軽量かつ強力なコードエディタであるVSCodeをベースとして環境を構築していきます。文章や表部分はMarkdownで記述し、図はUMLで記述します。

必要な拡張機能

VSCodeは、拡張機能(Extension)により、様々な機能をアドオンすることができます。

今回は、テキストだけでソフトウェア設計書を書くために、MarkdownとUMLに関する以下の拡張機能を使います。

Markdown Preview Enhanced

標準のMarkdownのプレビューでは図はイメージだけしか使えません。しかし、Markdown Preview Enhancedを使うと、PlantUMLというテキストだけで図が描ける拡張機能をMarkdownの中に含めることができ、さらにHTMLやPDFやWordなどの形式で出力できるようになります。

今回の環境ではVSCodeの次に重要な必須の拡張機能です。

PlantUML

図をテキストで描くために必要な拡張機能です。名前の通りUMLを描くことが目的ですが、ブロック図のような図も描くことができます。

Prettier - Code formatter

コードフォーマッタです。「Shift」+「Alt」+「F」のショートカットキーでドキュメントを整形してくれる拡張機能です。

markdownlint

その名の通り、Markdownのlintツール(書式のルールをチェック、指摘するツール)です。

Markdown All in One

Markdownのコードアシストといったところですか。

改行時に次のコードを入れてくれたりしてくれる拡張機能です。

上記のようにいろいろな拡張機能を使いますが、主要な拡張機能は、Markdown Preview EnhancedとPlantUMLです。その他は、Markdownをより効率的に記述するための補助機能です。

必要なソフトウェア

Markdown Preview Enhancedは、プレビューした結果をHTMLやPDFやWordなどの形式に出力することができますが、Word形式のファイルに出力するために、以下のソフトウェアをインストールする必要があります。また、PlantUMLを動かすためのソフトウェアもインストールする必要があります。

Pandoc

MarkdownをPDFやWord形式のファイルに変換するソフトウェアです。

Imagemagick

PlantUMLで生成した図面(SVG形式)を画像ファイルに変換するソフトウェアです。

graphviz(PlantUML1.2020.21以降は不要になりました)

PlantUMLで機能が内臓されたようです。(参考：Test your GraphViz installation (plantuml.com))

PlantUMLが図をイメージ化するために使用するソフトウェアです。

Java

PlantUMLの動作に必要なソフトウェアです。

上記のようにいろいろなソフトウェアの組み合わせで出来るので、環境構築には苦労します。

まとめ

今回は、VSCodeをMarkdownとUMLを使って文書を書き、最終的にはMicrosoftのWord形式のファイルを生成する方法の概要を紹介しました。

次回は、VSCodeによりテキストだけで文書をWord形式で出力できるようにするために必要なソフトウェアをインストールしていきます。

前の記事

Visual Studio CodeでProxy(認証あり)を設定する方法

次の記事

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築1)

関連記事

(8)Pythonの仮想環境をバージョン指定で切り替える

2021/03/05 13:48

                    Anacondaの有償化の対策として、Windows上での複数のPythonのバージョンの仮想環境の作成方法を紹介します。

この方法により、Anacondaほどではありませんが、自分の作ったテンプレート的な仮想環境を使いまわすことが可能になります。

Kali Linux 2020.4のインストール手順(Raspberry Pi 4B版)

2021/02/23 21:57

                    Raspberry Pi 4BにKali Linux 2020.4を入れてみたときの手順を紹介します。

Kali Linux 2020.4 のインストール後の初期設定

2021/02/20 14:00

                    Kali Linux 2020.4のインストール後の初期設定の手順概要を紹介します。

Kali Linux 2020.4 インストール手順

2021/02/15 21:28

                    Kali Linux 2020.4のインストールの手順概要を紹介します。

Kali Linuxとは

2021/02/14 23:01

                    Kali Linux(カーリー・リナックス／カリ・リナックス)は、ペネトレーションテストを主な目的としているDebianベースのLinuxディストリビューションです。Kali…

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(PlantUMLによる作図1)

2019/05/30 11:02

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式の文書を生成する方法を練習してみます。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(設計書のテンプレートを作る)

2019/05/25 17:06

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式のソフトウェア設計書を実際に生成します。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築2)

2019/05/21 17:58

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式文書を生成するために必要な拡張機能のインストール方法と設定を紹介します。

Visual Studio Codeでソフトウェア設計書(Word文書)を書く環境を作る(環境構築1)

2019/05/20 23:54

                    Visual Studio Code(VSCode)でMarkdown Preview EnhancedとPlantUMLを使ってテキストだけでWord形式文書を生成するために必要なソフトウェアのインストール方法を紹介します。

Visual Studio CodeでProxy(認証あり)を設定する方法

2019/05/17 1:51

                    Visual Studio Code (VSCode)で認証のあるProxyを設定する方法を紹介します。