会社で開発をする時に、資料をどうするかを悩んで自動作成してくれる資料化を考慮することになりました。
以前の開発では、C#だったら、Ndocを、javaだったら、javadoc、javascriptやtypescriptの場合は、JSDocを利用して、資料化をコメントから自動作成するようにしました。このようなことにした理由としては、フロントとバックエンドの開発がほぼ分離されていて、開発者も分かれていたからでした。
しかしながら、この度は、フールスタック開発者としての経験を作りたい、必要にされている会社だったので、
自動化を行うツールを選定する時に悩みました。
条件として考えたのは以下のものです。
１．バックエンドとフロントエンド両方一つとしてできること。（すべての言語を対象にすること）
２．検索ができること。
３．別途のサーバが不要であること。
４．非公開でも大丈夫であること。
５．gulpのタスク化ができること。(buildと同時にさせたいから)
６．わかりやすく関係性などがグラフィックとしても表現できること。
７．追加の拡張機能などの追加が自由で、楽であること。
８．色んなコメント形式に対応すること。
９．無料であること。
１０．作成が速いこと。
上記の条件を考慮して、Doxygenを選定しました。
DoxygenにGraphvizを追加して利用すると、グラフィック化もされるので、良いかと思いました。
色んな言語をfilterを追加すれば、対応できるので、すべての対応ができると思いましたが、
scssのfilterはまだでした。それを作るには時間が無かったので、別途のsassdocを選定して、相互リンクをヘッダにつけるようにしました。
| ツール名 | 言語 | 公式サイト | 備考 |
|---|---|---|---|
| Doxygen | php, javascript, vue | https://www.doxygen.nl/ | http://www.doxygen.jp/ |
| Graphviz | php, javascript, vue | http://www.graphviz.org/ | |
| SassDoc | scss | http://sassdoc.com/ |
１．ダウンロードは下記のURLから該当OSへ当てはまるものをダウンロードしてください。
https://www.doxygen.nl/download.html
２．フォルダ構成は下記のようにしました。変更する場合は、\doc\doc_config\Doxyfileの内部のパスを変更する必要があります。
(\docのものは https://github.com/heedaily/doxygen_config/tree/main/doc
にあります。)
frontが該当プロジェクトフォルダです。
その配下にdocフォルダを入れてください。
doc_config : Doxygen設定ファイルや拡張機能のフォルダ
html : Doxygen出力先
scss : sassdoc出力先
scss_index.html : Doxygenとsassdocをつなぐhtmlファイル
３．scss_index.htmlを自分のプロジェクトに合わせて修正しましょう。
４．Doxyfile修正
下記の項目を自分のプロジェクトに合わせて修正してください。
PROJECT_NAME
PROJECT_BRIEF
PROJECT_LOGO
INPUT
５．その他の変更
５．１．外部リンクの追加などをメニューとして追加したい場合はDoxygenLayout.xmlを開いて下記の部分を追記します。
<tab type="user" visible="yes" url="../scss_index.html" title="SCSS">
</tab>
ポイントは「type="user" visible="yes"」です。
typeが"user"でなければ、urlの設定を行っても実際はつながらないです。
visibleが"yes"でなければ、表示されません。
５．２．デザイン
doxygen.cssを利用して、プロジェクトに合わせたデザインにしても良いですね。
５．３．ヘッダとフッター
leaf_header.htmlとleaf_footer.htmlを修正すれば、変更されます。
５．４．コード表示スタイル変更
https://highlightjs.org/へアクセスして、好きな設定をやってダウンロード後に
.\doc\doc_config\highlightへ入れてくれれば適応されます。
６．インストール
package.jsonに下記のパッケージをdevDependenciesに追記してください。
"doxygen": "^0.4.0",
"sassdoc": "^2.7.3",
"sassdoc-extras": "^2.5.1",
その後にnpmとかyarnを利用して、インストールしてください。
yarn
そうすると、下記のようにdoxygenが存在しないとのエラーメッセージが表示されます。
１．にてダウンロードしたdoxygenファイルを該当フォルダ「プロジェクトフォルダ/node_modules/doxygen/dist/1.9.3」へコピーして解凍します。
プロジェクトフォルダ/node_modules/doxygen/dist/1.9.3
その後、windowsだったら、ubuntuから、macだったら、コマンドから該当プロジェクトフォルダからGraphviz(クラスのグラフィック化)をインストールします。2.42.2バージョンでインストールしてください。
sudo apt install graphviz
dpkg -l graphviz
graphvizがどこにインストールされているかを確認します。
dpkg -L graphviz
正しくインストールされ、Graphvizファイルが有る位置を確認して、下記と相違がある場合は、Doxyfileを修正してください。
７．gulpのタスク追加
関連があるファイルは黄色になっているものです。
しかし、setting/_path.jsonとsetting/sassdoc.jsはtasks/doxygen.jsやtasks/sassdoc.js内に入れても大丈夫な内容です。
{
...
"sass_src": "https://github.com/xxxx/front",
"doc_config": "doc/doc_config/iconmonstr-leaf-1-32.png",
"doxygen_config": "doc/doc_config/Doxyfile",
"doxygen_src": "./**/*.*"
}
import path from "./_path.json";
export default {
dest: 'doc/scss',
verbose: true,
display: {
access: ['public', 'private'],
alias: true,
watermark: true,
},
groups: {
'undefined': 'Ungrouped',
},
basePath: path.sass_src,
shortcutIcon: path.doc_config
};
/**
* doxygen gulp task file
*/
import gulp from 'gulp';
import path from "../setting/_path.json";
const doxygen = require('doxygen');
/**
* doxygen gulp task
*/
gulp.task("doxygen", (done) => {
doxygen.run(path.doxygen_config, '1.9.3');
done();
});
/**
* sassdoc gulp task file
*/
import gulp from 'gulp';
import gutil from 'gulp-util';
import setting from '../setting/sassdoc';
import cssSetting from '../setting/css';
const destSourceMaps = !gutil.env.release;
const sassdoc = require('sassdoc');
/**
* sassdoc gulp task
*/
gulp.task("sassdoc", () => gulp
.src(cssSetting.src, { sourcemaps: destSourceMaps })
.pipe(sassdoc(setting))
.on('data', () => {})
);
import gulp from "gulp";
/* This is a gulp task that runs the following tasks in parallel:
- webpack
- css
- sassdoc
- doxygen
*/
gulp.task("build", gulp.parallel("webpack", gulp.series("css", "sassdoc", "doxygen")));
８．実行
下記のコマンドを実行してください。
gulp build
これで、doc\htmlやdoc\scssに資料が作成されていることが確認できます。