Documenter.jl本地找不到指定函数docstring但GitHub构建正常问题咨询

结论 #

该问题大概率为本地配置问题，并非Documenter.jl本身的缺陷，因为GitHub CI环境可正常构建，说明代码和文档编写逻辑本身没有问题，问题出在本地环境和CI环境的差异上。

可按以下优先级排查本地问题： #

• 模块加载&预编译缓存问题 #

  本地构建时Documenter可能加载了旧版本的预编译模块，未包含f的最新docstring：

  1. 先清空Julia本地预编译缓存：Windows环境删除%USERPROFILE%\.julia\compiled目录，Linux/macOS环境执行rm -rf ~/.julia/compiled
  2. 检查文档目录下的make.jl开头，确保显式将当前项目路径加入加载路径后再导入模块，写法参考：

  push!(LOAD_PATH, joinpath(@__DIR__, "..")) # 路径调整到指向项目根目录即可
  using my_module
  

  3. 本地启动Julia REPL，执行以下命令验证f的docstring是否可被正常读取：

  include("my_module.jl")
  @doc my_module.f
  

  如果REPL中可正常读取docstring，说明是Documenter构建时模块加载错误，否则为本地代码导入逻辑问题。

• 函数导出配置问题 #

  检查f和g的导出状态是否一致：如果g已经通过export g声明在模块导出列表中，而f未导出，且make.jl中没有显式导入f，就会出现该问题。可确认CI环境的make.jl是否有额外的导入语句如using my_module: f, g，而本地make.jl未同步该配置。

• 版本兼容问题 #

  比对本地Documenter.jl版本和CI环境使用的版本是否一致，大版本差异可能存在兼容问题，可通过项目根目录的Manifest.toml锁定Documenter版本和CI环境对齐，排除版本差异导致的异常。

内容的提问来源于stack exchange，提问作者joinijo