Doxygenをもう少し便利に使いたい[未達]
はじめに
先日、Doxygenについて記事を書きました。
Doxygenを使ってドキュメントをつくる
実際にDoxygenを使っていて、もう少し便利に使いたい、ここは注意しないといけない、など思ったところを書き残すための記事です。
最後は課題を残して終わりました。
参考サイト
-
PlantUMLをコマンドから操作するマニュアル
- plantuml公式サイトです
-
Writing documentation for OpenCV
- OpenCVのdoxygenドキュメントを書くための手引きです
準備
doxygenはインストールしてあることが前提。
また、graphvizを使うので、それも別途インストールしてある。
ディレクトリ
作業ディレクトリを準備します。
基本的には前回記事と同じです。
Graphvizとplantuml.jar
plantuml.jar
はC:\PlantUML
に入れておきます。
(plantuml.jar
については前回記事を参照)
graphviz
へパスが通っていることを確認する。
> java -jar C:\PlantUML\plantuml.jar -testdot
Dot version: dot - graphviz version 2.38.0 (20140413.2041)
Installation seems OK. File generation OK
PlantUMLをPNG画像として扱う
pu
フォルダーをつくって、その中に.pu
を集約する。
pu
ファイルに書かれたUMLからPNG画像ファイルを生成するコマンド。
java -jar C:/PlantUML/plantuml.jar <puファイル>
↑を打つとpu
ファイルと同じ階層にstartuml
の数だけPNGファイルが生成される。
これをいちいち打つのが面倒くさいから、VS Codeのタスクにする
{
"version": "2.0.0",
"tasks": [
{
# --- doxygen Doxyfileコマンドについて書かれている箇所
# --- 前回の記事を参照のこと
},
{
"label": "plantuml",
"type": "shell",
"command": ["java -jar C:/PlantUML/plantuml.jar ./pu -o ../images/pupng"],
"group": {
"kind": "build",
"isDefault": true
},
"presentation": {
"reveal": "always",
"clear": true,
"panel": "shared"
},
"options": {
"cwd": "${workspaceRoot}/workspace/src"
}
}
]
}
出力先のフォルダーは-o
オプションで指定
注意!出力先パスについて
PlantUML公式に書いてありますが、以下の通りとのこと。
相対パスで指定すると、画像ファイルは入力ファイルからの相対パスのディレクトリに出力されます。
java -jar C:\PlantUML\plantuml.jar .\workspace\src\puml\ -o ..\images\pupng
PNG画像にしたものを使う
PNG画像にしてしまえば、あとはリンクを貼る文法に「!」をつけて画像として埋め込むだけです
マークダウンに直接UMLを書くと長くなってしまうので、いったん画像にして埋め込むと見通しがよくなるので、一計かと。
外部PDFファイルを使う
参考にさせていただいた記事では、workspace
直下にextra
フォルダーを作っています。
機器マニュアルや論文などPDF形式で配布されることが多いファイルは、extra
フォルダーに格納します。
Doxygen GUIでは、ココ↓にパスを書きます。
同名の画像ファイルに注意
出力先のフォルダーは階層化されていないので、同名の画像ファイルは、どちらか一方の画像に上書きされる
# 同名のtestimage.pngだが絵柄は違う
![](images/testimage.png)
![](images/sub/testimage.png)
2種類の絵柄違いのtestimage.png
を表示させているつもりでも
出力先のフォルダーにはtestimage.png
は1つしかないので、どちらかの絵柄データがもう片方の絵柄データで上書きされている。
どうするのが正解なのか
この記事の最終節です。
OpenCVもdoxygenを使っているのでうまくやっているのかと思いきや
git pull
してdoc
の中でjpg
ファイルを検索すると
見事にファイル名がばらばらで、うまいこと画像名が重複しないようにしているようにみえました。
result.jpg
なんて気を抜けばすぐに同じ画像を作ってしまいようだけど・・・。
サブディレクトリに振り分けて同じ画像名を判別できるようにする術はないものか。
調べても現時点では埒が明かないので終わりにします。
op