# TODO: gtool5 Doxygen 移行作業

最終更新: 2026-02-02

---

## 完了済み作業

### 1. RDoc -> Doxygen ドキュメント変換 (全ディレクトリ完了・コミット済み)

以下のディレクトリの Fortran ソースファイルを RDoc 形式から Doxygen Markdown 形式へ変換済み:

| ディレクトリ                           | ファイル数 | 状態       |
|----------------------------------------|-----------|------------|
| src/dc_utils/                          | (参考例)  | 変換済み   |
| src/gtdata/                            | 40        | 変換済み   |
| src/gtdata/gtdata_netcdf/              | 24        | 変換済み   |
| src/gtdata/gtdata_netcdf_file/         | 10        | 変換済み   |
| src/gtool/gtool_history/               | 43        | 変換済み   |
| src/gtool/gtool_history_nmlinfo/       | 24        | 変換済み   |
| src/gtool/gtool_historyauto/           | 13        | 変換済み   |

### 2. doc/ 構成の調査 (完了)

- [x] `doc/doxyfile.in` - Doxygen 1.15.0 形式、全 2986 行を確認
- [x] `doc/doxyfile.in.bak` - Doxygen 1.9.1 時代のバックアップ
- [x] `doc/assets/header-ja.html` / `header-en.html` - Bootstrap 5 navbar + 日英切替
- [x] `doc/assets/footer.html` - Copyright + 日英切替 JS (jQuery 依存)
- [x] `doc/assets/layout.xml` - Doxygen 1.9.1 生成、pages/files/examples コメントアウト
- [x] `doc/assets/gtool.css` - カスタム CSS (フォント、配色 #224422/#338833)
- [x] `configure.ac` 内の doxygen 関連設定 - `AC_CHECK_PROGS`, `AM_CONDITIONAL`
- [x] doxygen-awesome の参照箇所検索 - **ソースコード中に参照なし** (使用していない)
- [x] Doxygen 1.15.0 デフォルトテンプレートとの比較

### 3. Doxygen ドキュメント生成の再構成 (完了)

Bootstrap 5 / jQuery / SmartMenus 等の外部ライブラリへの依存をやめ、
Doxygen 1.15.0 のデフォルトテンプレートをベースにゼロから再構成した。

- [x] header-ja.html / header-en.html: デフォルトテンプレートベースに書き換え
  - 日英切替リンクを TITLEAREA テーブル内に配置
  - Bootstrap/jQuery/SmartMenus の読み込みを削除
  - Doxygen 標準の `$mathjax`, `$darkmode`, `$extrastylesheet` 変数を活用
- [x] footer.html: デフォルトテンプレートベースに書き換え
  - 日英切替 JavaScript を vanilla JS で実装 (jQuery 依存を除去)
- [x] layout.xml: 1.15.0 デフォルトで置き換え
- [x] doxyfile.in の更新
  - MathJax: CDN 利用 (`MATHJAX_VERSION = MathJax_4`)
  - HTML_EXTRA_FILES: Bootstrap/jQuery 関連を全て削除
  - HTML_EXTRA_STYLESHEET: `doc/assets/custom.css` を指定
  - HTML_COLORSTYLE: LIGHT に変更
- [x] Makefile.am: mathjax-v3.2.0 コピー処理を削除
- [x] custom.css の作成
  - フォントサイズ: px 決め打ちを rem ベースに変更
  - フォント指定: CSS 変数でサンセリフ/等幅を一元管理
  - 言語切替リンクのスタイル
- [x] テストビルド成功

### フォーマット仕様 (変換ルール)

- 行頭は `!>` で始める (Fortran 90 以降のコメント形式)
- 日英併記: 英語は `@en` 〜 `@enden`、日本語は `@ja` 〜 `@endja` で囲む
- subroutine/function には `@param[in]`, `@param[out]`, `@param[inout]`, `@return` を追加
- RDoc クロスリファレンス `module#Type` -> Doxygen `module::Type` に変換
- 参考例: `src/dc_utils/dc_types.f90`
- **重要**: `.rb2f90` ファイル内の Ruby テンプレートコード (`#{ifelse(...)}`, `#{forloop(...)}` 等) は絶対に削除しない
- **重要**: CLEANFILES に含まれる .f90 は生成物のため、生成元 .rb2f90 を編集する

---

## 残作業

### doc/assets/ の整理 (完了)

- [x] 不要ファイルの削除: Bootstrap, jQuery, jQuery UI, SmartMenus,
  PowerTip, MathJax ローカルコピー (mathjax-v3.2.0/)
- [x] doxyfile.in.bak の削除

### ページ構成の見直し (完了)

- [x] 英語版で Related Pages が生成されない問題の修正
  - 原因: README.md 英語セクションで `\subpage` を使用 → 全ページがサブページ化 → Related Pages が空
  - 修正: 日英両方で `@ref` に統一し、全4ページを Related Pages に表示

### 1. チュートリアルの markdown 化 (進行中)

doc/old/tutorial/*.rd を doc/tutorial/*.md に変換する。
詳細は下記「チュートリアル調査結果」および「チュートリアル変換方針」を参照。

#### dc_args チュートリアル変換 (完了・ビルド確認済み)

1. [x] doc/tutorial/ ディレクトリを作成
2. [x] doc/old/tutorial/dc_args/ を doc/tutorial/dc_args/ にコピー
3. [x] dc_args/diffusion_7.f90 に `!> [tag]` snippet マーカーを追加
   - `[dc_args_use]`, `[dc_args_vars]`, `[dc_args_calls]` の 3 タグ
4. [x] dc_args.rd を doc/tutorial/dc_args.md に変換
5. [x] doxyfile.in の EXAMPLE_PATH, IMAGE_PATH を更新
6. [x] src/dc_utils/dc_args.f90 のチュートリアルリンクを `@ref tutorial_dc_args` に書き換え
7. [x] ビルドして見た目を確認

#### チュートリアルインデックス (完了・ビルド確認済み)

- [x] doc/old/tutorial/index.rd を doc/tutorial/index.md に変換 (アンカー: `{#tutorials}`)
- [x] README.md の「チュートリアル」「Tutorial」を `@ref tutorials` でリンク化

#### Markdown ページタイトルに関する注意

- Doxygen Markdown は冒頭行をスキャンしてページタイトルとする
- `# Title {#anchor}` は `@ja`/`@en` で囲まず、**英語のみ** で記述すること
- セクション見出し (`##` 以下) は `@ja`/`@en` で分離して問題ない

#### 次のアクション: 残り 20 個の .rd ファイルを変換

変換順の推奨: 日英併記 (8ファイル) → 日本語のみ (12ファイル)

**日英併記 (dc_args 以外の 8 ファイル)**:
dc_types, dc_message, dc_calendar1, dc_calendar2, dc_clock, dc_trace, dc_date

**日本語のみ (12 ファイル)**:
gthist_first, gthist_gave, gthist_desc, gthist_attr, gthist_multi,
gthist_restart, gthist_f77, gtauto_first, gtauto_first2, gtauto_desc,
gtauto_desc2, examples

各ファイルの変換手順:
1. サブディレクトリ (サンプルコード) があれば doc/tutorial/ にコピー
2. サンプル .f90 に `!> [tag]` snippet マーカーを追加
3. .rd を .md に変換 (英語タイトル + `@ja`/`@en` で本文分離)
4. src/ 内の対応する .f90 のチュートリアルリンクを `@ref` に書き換え
5. ビルド確認

src/ 内リンク書き換えの残り:
- `src/dc_utils/dc_calendar.f90` → `@ref tutorial_dc_calendar1`, `@ref tutorial_dc_calendar2`
- `src/dc_utils/dc_date.f90` → `@ref tutorial_dc_date`
- `src/gtool/gtool_historyauto/gtool_historyauto.f90` → チュートリアルURL追加が必要

### 2. カスタム CSS (配色等)

- [ ] 旧テーマの配色 (#224422/#338833) の再現検討

### 3. ヘッダー・フッター

- [ ] GFD Dennou Club 等への外部リンクの追加
- [ ] Copyright 表記の追加

### 4. MathJax ローカル運用

- CDN 利用は完了済み。オフライン対応は下記「MathJax に関する方針と課題」を参照。

---

## チュートリアル調査結果

### ファイル構成

doc/old/tutorial/ に 21 個の .rd ファイル、13 個のサブディレクトリ (サンプルコード・データ・画像 計45個)。

#### 日英対応状況

**日英併記 (9ファイル)**: index, dc_types, dc_message, dc_calendar1, dc_calendar2, dc_clock, dc_trace, dc_args, dc_date

**日本語のみ (12ファイル)**: gthist_first, gthist_gave, gthist_desc, gthist_attr, gthist_multi, gthist_restart, gthist_f77, gtauto_first, gtauto_first2, gtauto_desc, gtauto_desc2, examples

#### サブディレクトリ (サンプルファイル)

dc_args/ (1), dc_calendar/ (4), dc_clock/ (1), dc_date/ (1),
dc_message/ (1), dc_trace/ (1), dc_types/ (1), gtauto_first/ (7),
gthist_attr/ (2), gthist_f77/ (3), gthist_first/ (3),
gthist_gave/ (13 png), gthist_multi/ (7)

### RD 形式の特徴

- `=begin JA`/`=end JA`, `=begin EN`/`=end EN` で日英分離
- `=begin HTML`/`=end HTML` に `<pre>` でソースコード表示
  - `<b><font color="red">` で変更箇所をハイライト (計46個の HTML ブロック)
- `=` h1, `==` h2, `===` h3
- `((<text|URL:path>))` リンク、`((*text*))` 太字
- `: term` 定義リスト

### Doxygen 設定の現状

- `INPUT` に `@top_srcdir@/doc` 含む、`RECURSIVE = YES`、`FILE_PATTERNS` に `*.md`
- `EXCLUDE_PATTERNS` に `*/old/*` → doc/old/ は除外済み
- `EXAMPLE_PATH` と `IMAGE_PATH` に `@top_srcdir@/doc/tutorial` を設定済み
- → doc/tutorial/*.md に配置すれば自動的に取り込まれる

### ソースコードからの参照 (要書き換え)

以下の src/ 内 Fortran ドキュメントからチュートリアルページへのリンクがある。
変換後は `@ref tutorial_xxx` に書き換えが必要。

| ソースファイル | リンク先 (旧パス) |
|--------------|------------------|
| `src/dc_utils/dc_args.f90:19,49` | `../tutorial/dc_args.htm{,.en}` |
| `src/dc_utils/dc_calendar.f90:17-18,38-39` | `../tutorial/dc_calendar{1,2}.htm{,.en}` |
| `src/dc_utils/dc_date.f90:16,40` | `../tutorial/dc_date.htm{,.en}` |
| `src/gtool/gtool_historyauto/gtool_historyauto.f90:40-41,81-82` | リンク URL なし (テキストのみ、URL 追加が必要) |

---

## チュートリアル変換方針 (決定済み)

### コード表示: @snippet 方式

.f90 サンプルファイルに `!> [tag]` マーカーを埋め込み、
markdown 側で `@snippet` で抜粋表示する。

```fortran
!> [history_use]
use gtool_history                             ! モジュール指定
!> [history_use]
```

```markdown
@snippet gthist_first/diffusion_1.f90 history_use
```

- .f90 は単独でダウンロード・コンパイル可能 (`!>` は Fortran コメント)
- チュートリアルでは変更箇所を抜粋表示 + 全体は @include またはリンクで参照
- 赤字の完全再現ではないが、「重要箇所を抜き出して説明」という目的は果たせる

### ページ構成

- 各 .rd → doc/tutorial/xxx.md に変換
- 先頭に `{#tutorial_xxx}` アンカーを付与 (@ref でリンク可能に)
- `=begin JA`/`=end JA` → `@ja`/`@endja`
- `=begin EN`/`=end EN` → `@en`/`@enden`
- 日本語のみのページは `@ja`/`@endja` で囲み、英語は後日追加可能な状態にする
- サブディレクトリのサンプルファイルは doc/tutorial/ 以下にそのまま移動

### RD → Markdown 変換ルール

| RD 記法 | Markdown/Doxygen |
|---------|-----------------|
| `=begin JA` ... `=end JA` | `@ja` ... `@endja` |
| `=begin EN` ... `=end EN` | `@en` ... `@enden` |
| `= Title` | `# Title {#tutorial_xxx}` |
| `== Title` | `## Title` |
| `=== Title` | `### Title` |
| `((<text\|URL:path>))` | `[text](path)` or `[text](@ref anchor)` |
| `((*text*))` | `**text**` |
| `: term` 定義リスト | `**term**` + 説明文 |
| `=begin HTML` `<pre>` コード | `@snippet file tag` or `@include file` |
| `=begin HTML` フッター | 削除 ($Id$ 等は不要) |

### doxyfile.in の変更

- `EXAMPLE_PATH` に `@top_srcdir@/doc/tutorial` を追加
- `IMAGE_PATH` に `@top_srcdir@/doc/tutorial` を追加 (gthist_gave の .png 用)

### 検証方法

```
autoreconf -fi && ./config.status && make && make html
```

**configure のフラグは複雑なため、html 生成前に必ずユーザに確認すること。**

確認項目:
- doc/html/ja/ と doc/html/en/ にチュートリアルページが生成されるか
- @snippet によるコード抜粋が正しく表示されるか
- @ref tutorial_dc_args 等のクロスリファレンスが機能するか
- サンプルファイルへのリンクが有効か

---

## MathJax に関する方針と課題

### 当面の方針

Doxygen の `$mathjax` 変数を使い、CDN から MathJax を読み込む:

```
USE_MATHJAX     = YES
MATHJAX_VERSION = MathJax_4
MATHJAX_RELPATH = (デフォルト CDN: https://cdn.jsdelivr.net/npm/mathjax@4)
```

### ローカル (オフライン) 運用の課題

- Doxygen は MathJax の JS/CSS を HTML 出力に同梱 **しない**
  (CDN/ローカルパスへの `<script src>` を生成するのみ)
- オフライン環境で数式を表示するには MathJax ローカルコピーが必要
- 現在 `doc/assets/mathjax-v3.2.0/` にローカルコピーがある (数 MB)
- Doxygen 1.15.0 は `MATHJAX_RELPATH/es5/tex-chtml.js` を参照するが、
  ローカルコピーは `mathjax-v3.2.0/tex-chtml.js` (es5/ サブディレクトリなし)
- ローカル運用に切り替える場合:
  - `es5` シンボリックリンクの作成、またはディレクトリ構造の変更が必要
  - `MATHJAX_RELPATH = ../mathjax-v3.2.0` に設定
  - Makefile.am で mathjax を html/ にコピーする処理を復活
- 現行ヘッダーでは physics パッケージを読み込んでいた
  → ローカル運用時は `MATHJAX_CODEFILE` でカスタム設定を指定可能

---

## メモ

- `src/dc_utils/` 以下の変換は本セッション以前に完了済み (参考例として使用)
- src/gtdata/ 以下 11 ファイルで subroutine 宣言が誤削除された問題は修正済み
  (gdncvargetnum.f90, gdncvarputnum.f90 は .erb 生成物のため削除で正しい)
- `doc/README.md` は `../README.md` へのシンボリックリンク (正常)