doc/ ディレクトリに用途の異なるファイルが混在しているため置き場を整理する
概要
doc/ に、doxygen の入力ファイル・開発者向け解説文書・解説文書に埋め込む画像・README 用画像が、用途別に分かれずに同居している。
※以下は !587 (merged) のマージ後に残るファイルのみ記載している。
| 系統 | ファイル | 用途 |
|---|---|---|
| doxygen(ビルド生成物の入力) | doc/Doxyfile.in, doc/fistr.css, doc/fistr_logo.png |
WITH_DOC=ON のとき CMake がビルドディレクトリへ展開し doxygen が読む |
| 開発者向け解説文書 | doc/CICD/manual.md |
CI/CD 構成の説明。ビルドにも CI にも読まれない |
| 解説文書に埋め込む画像 | doc/CICD/download_list.png, doc/CICD/library_dependency.png |
doc/CICD/manual.md からのみ参照 |
| README 用画像 | doc/FrontISTR_logo.svg |
README.md / README.ja.md からのみ参照 |
実害
名前から用途が判別できず、変更・削除の可否判断にコストがかかる。
doc/fistr.css と doc/fistr_logo.png は、doc/ という配置からマニュアル(mkdocs)向けの成果物である可能性を排除できず、以下の参照経路を追跡して初めて doxygen 用と確定できた。
CMakeLists.txt:426 if(WITH_DOC) / if(DOXYGEN_FOUND)
├─ :429 doc/fistr.css → ${CMAKE_BINARY_DIR}/doc/ へコピー
├─ :430 doc/fistr_logo.png → ${CMAKE_BINARY_DIR}/doc/ へコピー
└─ :435 doc/Doxyfile.in → ${CMAKE_BINARY_DIR}/doc/Doxyfile へ configure_file
├─ Doxyfile.in:54 PROJECT_LOGO = @CMAKE_CURRENT_BINARY_DIR@/doc/fistr_logo.png
└─ Doxyfile.in:1188 HTML_EXTRA_STYLESHEET = @CMAKE_CURRENT_BINARY_DIR@/doc/fistr.css提案
doxygen の入力一式を doc/doxygen/ のような専用サブディレクトリへ移し、doc/ 直下には用途の異なるファイルを置かない方針とする。
パス変更に伴い CMakeLists.txt、doc/Doxyfile.in、README.md、README.ja.md の同時修正が必要となる。