使用python-sphinx autodoc生成API文档时与Jupyter-Book样式兼容问题

问题背景 #

我用Jupyter-Book为Python包构建文档，已完成基础部署：通过CI/CD执行jupyter-book build documentation/自动构建并发布。当前用Jupyter Notebook制作用户指南、Markdown做静态页面，Sphinx Autodoc生成API文档（刚接触Sphinx），现需优化API文档的两个样式问题：

1. API文档页面无右侧侧边栏，无法快速导航类方法或模块函数
2. 参数列表挤在括号内，类名显示完整模块路径，期望优化为：

class BaseTokenizer(string: str = '', 
                    subtoksep: chr = ' ', 
                    intervals: Union[None, EvenSizedSortedSet] = None, 
                    tokens: list = [])

而非当前的冗长格式：

class iamtokenizing.base_tokenizer.BaseTokenizer(string: str = '', subtoksep: 
chr = ' ', intervals: Union[None, 
extractionstring.even_sized_sorted_set.EvenSizedSortedSet] = None, tokens: list = [])

解决方案 #

1. 恢复API页面右侧侧边栏导航 #

• 调整Jupyter-Book配置文件_config.yml：在html_theme_options中添加show_sidebar: true，并设置show_toc_level: 3（确保方法、函数级内容能显示在侧边栏）
• 检查_toc.yml配置：确保API章节正确关联到autodoc生成的rst文件，示例：

  - file: api/index
    sections:
      - file: api/chargrams
  

• 启用Sphinx扩展：在documentation/source/conf.py中添加sphinx.ext.autosummary和sphinx.ext.viewcode扩展，帮助生成带导航结构的API文档
• 确保rst文件的autodoc指令正确：比如使用automodule:: iamtokenizing.chargrams并添加:members:参数，让所有成员被收录到文档结构中

2. 优化参数格式与类名显示 #

• 简化类名：在conf.py中添加add_module_names = False，Autodoc将只显示类/函数的短名称，而非完整模块路径
• 参数换行缩进：
  1. 启用sphinx.ext.napoleon扩展（支持Google风格docstring，自动格式化参数列表），在conf.py中配置：

     extensions = [
         # 其他已启用的扩展
         'sphinx.ext.napoleon',
     ]
     napoleon_use_param = True
     

  2. 优化类型提示显示：在conf.py中添加python_use_unqualified_type_names = True，让类型中的类名只显示短名称（如EvenSizedSortedSet而非完整路径）
  3. 如需更精细控制，可安装sphinx_autodoc_typehints扩展，配置：

     extensions.append('sphinx_autodoc_typehints')
     typehints_defaults = 'braces'
     typehints_use_rtype = False
     

生效方式 #

修改所有配置后，重新执行jupyter-book build documentation/即可生效。若以上配置无法解决问题，再考虑向Jupyter-Book或Sphinx官方仓库提交issue。

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