[Boto3 Adv-Cal DAY21]Doxygenの出力設定を調整してみた

boto3 で楽しむ AWS PythonLife 一人AdventCalendarです。21日目はDoxygenにてドキュメントを生成する際の最適なパラメータを調整してみました。
2018.12.21

boto3 で楽しむ AWS PythonLife 一人AdventCalendarです。

boto3のドキュメントを通して、サービス別にどういった事が出来るのかを理解したり、管理コンソールを通さずにTerminalだけで完結できるように検証していくことが目的になります。

21日目はDoxygenの出力設定をBoto3に合わせて細かくチューニングしてみました。

目次

対象となるパラメータについて

Boto3はAWSのAPIへ呼び出しを掛けるWrapperのような役割のため、そこまで細かい設定をしなくても、割と丁度よく出力されます。ですが、プライベートメンバーについては手を加える必要があります。

PROJECT_NAME

My ProjectからBoto3に変更します。タイトル変更のため解析そのものに影響はありません。

% sed -i "" -e "s/PROJECT_NAME +=.+$/PROJECT_NAME         = \"Boto3\"/" reference

PROJECT_NAME = "Boto3"

PROJECT_NUMBER

リリースバージョンを差し替えます。setup.pyversionが定義されているので、それを利用します。

% python setup.py --version | xargs  -I{} sed -i "" -e "s/PROJECT_NUMBER +=.+$/PROJECT_NUMBER         = {}/" reference

PROJECT_NUMBER = 1.9.69

EXTRACT_PRIVATE

プライベートメンバーとして定義されているものを出力します。Boto3の実装がそもそも薄いこともあり、ボリュームも薄いだろうと判断して追加しています。

% sed -i "" -e "s/EXTRACT_PRIVATE +=.+$/EXTRACT_PRIVATE         = YES/" reference

EXTRACT_PRIVATE = YES

EXTRACT_PACKAGE

全スコープのパッケージ名を出力します。同じくボリュームも薄めであると想定した上です。

% sed -i "" -e "s/EXTRACT_PACKAGE +=.+$/EXTRACT_PACKAGE         = YES/" reference

EXTRACT_PACKAGE = YES

EXTRACT_STATIC

スタティックのメンバーを出力します。

% sed -i "" -e "s/EXTRACT_STATIC +=.+$/EXTRACT_STATIC         = YES/" reference

EXTRACT_STATIC = YES

INTERNAL_DOCS

内部コマンドのドキュメントを出力します。

% sed -i "" -e "s/INTERNAL_DOCS +=.+$/INTERNAL_DOCS         = YES/" reference

INTERNAL_DOCS = YES

INPUT

リソースのディレクトリを指定します。

% sed -i "" -e "s/INPUT +=.+$/INPUT         = .\/boto3/" reference

INPUT = ./boto3

RECURSIVE

サブディレクトリから回帰的に取得するため指定します。

% sed -i "" -e "s/RECURSIVE +=.+$/RECURSIVE         = YES/" reference

RECURSIVE = YES

MAN_LINKS

ドキュメントのリンクを有効にしておきます。

% sed -i "" -e "s/MAN_LINKS +=.+$/MAN_LINKS         = YES/" reference

MAN_LINKS = YES

一括実行

上記のコマンドの一括実行を行う場合は以下の通りです。初回以降は、更新が入った際にversionを反映する程度になると思います。

% python setup.py --version | xargs  -I{} sed -i "" -e "s/PROJECT_NUMBER +=.+$/PROJECT_NUMBER         = {}/" reference
% sed -i "" \
 -e "s/PROJECT_NAME +=.+$/PROJECT_NAME         = \"Boto3\"/" \
 -e "s/EXTRACT_PRIVATE +=.+$/EXTRACT_PRIVATE         = YES/" \
 -e "s/EXTRACT_PACKAGE +=.+$/EXTRACT_PACKAGE         = YES/" \
 -e "s/EXTRACT_STATIC +=.+$/EXTRACT_STATIC         = YES/" \
 -e "s/INTERNAL_DOCS +=.+$/INTERNAL_DOCS         = YES/" \
 -e "s/INPUT +=.+$/INPUT         = .\/boto3/" \
 -e "s/RECURSIVE +=.+$/RECURSIVE         = YES/" \
 -e "s/MAN_LINKS +=.+$/MAN_LINKS         = YES/" reference

まとめ

Doxygenのパラメータは納得いくまで調整する必要もあり、一筋縄では行かないケースも多々あります。

丁度いいパラメータさえ見つけてしまえば、基本は差分取得時に実行するだけになるので、根気の良さが大事かもしれません。