FortranのドキュメントをFORDで自動生成した話
諸事情により書いたものをここに乗せることができないので私の書いたものはここにありません.
Fortranを書く機会があり,そのドキュメントを作成する必要があったのでドキュメント自動生成ツールを調べた.
Fortranのドキュメントツールをいくつか上げるとこんな感じ.
- f90doc
- f90tohtml
- FortranDOC
- FORD
詳しくは fortranwiki.org
にいくつか乗っていて,
で比較されている.
今回は,FORDがfortran2003の文法にも対応しているので採用. 本家はここ.
使い方
トップページ用にHoge.mdを書いて,ford Hoge.md
とすればドキュメントが生成される.
ソースコードのあるディレクトリはコマンドライン引数で--src_dir fuga/src
と指定するか
Hoge.mdの中に書く.
Hoge.mdはこんな感じで書く.
summary: poyo src_dir: fuga/src piyo/src Main sentences in markdown.
markdown metadeta を使ってドキュメント生成の設定ができる. 公式のWikiもあるので詳細はそっちで.
Home · Fortran-FOSS-Programmers/ford Wiki · GitHub
使ってみて感想
いいところ
- pipで入る・コマンド一発でビルドという簡単さ
- MathJax対応
- プリプロセッサを使ってくれるのでマクロでいろいろできる
- ドキュメントをmarkdownでかける
- htmlで吐き出されるので見るのが楽
ソースコードから自動生成されるドキュメントの見た目はまあ普通.
あとドキュメントに反映させるためのコメントは定義分の下に書かないといけないというのがもともとの実装.
こんな感じで.
function hoge !! comment
調べてみて, github.com
を読む限り変更されてないようなオチに読み取れてしまったのだけど
でちゃんとマージされてて
!> comment function hoge
と書けば可能.
これなら今までどおり定義文の上にコメントをかけるのでめでたい.
不満
- トップページのSource Codes がディレクトリごとになってほしい
- Source Code上で関数を呼び出してるところをクリックしたら定義に飛んでほしい
- もうちょっとサンプルコードほしい
まとめ
割と簡単にドキュメントが作成できたし,開発が止まっていないので,使う価値はあるのではないでしょうか.