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