Debian 环境下 Fortran 文档编写与生成
工具选型与对比
- 在 Debian 上，常用的 Fortran 文档工具有：
- Doxygen：通用文档生成器，支持 Fortran，可输出 HTML、LaTeX（转 PDF）、XML、RTF、PostScript、Unix Man 等；适合与既有 C/C++ 项目共用同一套流程。
- FORD：专为 Modern Fortran 设计，支持 Markdown、交叉引用、模块依赖图、LaTeX 公式，输出美观的 HTML 文档，上手简单。
- Sphinx-Fortran：基于 Sphinx/Python 的扩展，适合需要融入 Sphinx 生态（如 Read the Docs）的项目。
- 其他工具：f90doc、f90tohtml、Doctran、Flint 等，可视项目风格与需求选用。
- 若需要编辑器内提示与跳转，可配合 fortran-language-server（fortls），其对 Doxygen 与 FORD 风格的注释有解析能力，支持符号跳转、悬停查看文档等 LSP 功能。
快速上手 Doxygen
- 安装
- 在 Debian/Ubuntu 上安装：sudo apt-get install doxygen；如需图形界面：sudo apt-get install doxygen-gui（命令为 doxywizard）。
- 可选：安装 Graphviz 以生成调用/依赖关系图：sudo apt install graphviz。
- 生成配置
- 在项目根目录执行：doxygen -g 生成默认配置文件 Doxyfile；按需修改关键项（如 INPUT、OUTPUT_DIRECTORY、PROJECT_NAME、GENERATE_LATEX、HAVE_DOT、EXTRACT_ALL、SOURCE_BROWSER 等）。
- 编写注释
- 启用 Fortran 支持（在 Doxyfile 中设置 ENABLED_SECTIONS = Fortran 等），并按 Doxygen 风格注释函数/模块/变量；Doxygen 支持多种输出格式，便于生成在线 HTML 与可打印 PDF（经 LaTeX）。
快速上手 FORD
- 安装
- 推荐使用 pip：pip install ford；或从源码安装：git clone https://github.com/Fortran-FOSS-Programmers/ford.git && cd ford && pip install .
- 编写注释
- 以 !> 开头的注释会被识别为文档块，支持 @brief、@details、@param[in/out]、@return 等标签，也支持 Markdown 与 LaTeX 公式，适合现代 Fortran 项目组织 API 文档。
- 配置与生成
- 创建配置文件（如 ford.yml），指定项目信息、源码目录、输出目录、是否生成依赖图等；运行：ford ford.yml，在输出目录打开 index.html 查看。
注释规范与编辑器支持
- 注释规范建议
- 文件级：在文件头概述功能、作者、版本、依赖与使用范例。
- 模块/类型：在 type/end type 或 module/end module 附近说明用途、接口与注意事项。
- 函数/子程序：在 function/subroutine 下一行或 !> 块中写明功能、参数语义、返回值、版本与示例；对关键算法给出 @details 与公式。
- 编辑器与语言服务器
- 使用 fortls 可在 Emacs、Vim 等编辑器内获得符号导航、悬停文档（解析 Doxygen/FORD 风格）、重命名与诊断等体验，显著提升编写与维护效率。
实用命令清单
- Debian 安装常用组件：sudo apt-get install doxygen；如需 GUI：sudo apt-get install doxygen-gui；如需图形：sudo apt install graphviz。
- Doxygen：doxygen -g（生成配置）；编辑 Doxyfile 后运行 doxygen 生成文档（HTML/LaTeX 等）。
- FORD：pip install ford；配置 ford.yml 后运行：ford ford.yml 生成 HTML 文档。