あおかびのおすなば

日々のコトとかなんか見た感想とか

FortranのドキュメントをFORDで自動生成した話

諸事情により書いたものをここに乗せることができないので私の書いたものはここにありません.

Fortranを書く機会があり,そのドキュメントを作成する必要があったのでドキュメント自動生成ツールを調べた.

Fortranのドキュメントツールをいくつか上げるとこんな感じ.

  • f90doc
  • f90tohtml
  • FortranDOC
  • FORD

詳しくは fortranwiki.org

にいくつか乗っていて,

www.gfd-dennou.org

で比較されている.

今回は,FORDがfortran2003の文法にも対応しているので採用. 本家はここ.

github.com

使い方

トップページ用に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

を読む限り変更されてないようなオチに読み取れてしまったのだけど

github.com

でちゃんとマージされてて

!> comment
function hoge

と書けば可能.

これなら今までどおり定義文の上にコメントをかけるのでめでたい.

不満

  • トップページのSource Codes がディレクトリごとになってほしい
  • Source Code上で関数を呼び出してるところをクリックしたら定義に飛んでほしい
  • もうちょっとサンプルコードほしい

まとめ

割と簡単にドキュメントが作成できたし,開発が止まっていないので,使う価値はあるのではないでしょうか.