使用pdoc3生成项目文档时函数参数类型无法生成为链接如何解决

• 首先确保项目根目录存在空的__init__.py文件，将目录标记为Python包，方便pdoc扫描所有模块。
• 修正api.py的导入规则，使用显式的非别名导入引入model中的自定义类型，不要使用相对导入或者别名导入，示例：

  # api.py开头导入示例
  from model import User, Auth, CreateUserApiCallResult
  

• 生成文档时将整个项目目录作为输入，不要只单独传入单个api.py文件，示例生成命令：

  pdoc --html your_project_root/
  

• 如果你在代码中开启了from __future__ import annotations延迟类型注解特性，需要在生成命令中添加--type-checking参数，让pdoc主动解析字符串形式的类型注解：

  pdoc --html --type-checking your_project_root/
  

• 以上配置完成后仍未生成跳转链接的话，可以在函数docstring中使用pdoc内置的引用语法手动绑定类型链接：

  def create_user(auth: Auth, user: User) -> CreateUserApiCallResult:
      """
      Create a User
      参数说明：
      auth: 接口鉴权信息，类型参考 [model.Auth]
      user: 待创建的用户数据，类型参考 [model.User]
      返回值：接口调用结果，类型参考 [model.CreateUserApiCallResult]
      """
      return create_users(auth, [user])
  

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