Sphinx主题开发：静态目录新增sample文件夹未被构建复制的解决方法

以下是几种可行的解决方法：

• 确认conf.py的静态路径配置
  检查项目根目录下conf.py中的html_static_path，确保主题的静态目录已被正确添加。若是自定义主题，需同时确认主题的theme.conf里staticdir字段指向正确的静态目录路径。示例配置：

  html_static_path = ['_static']
  

• 用html_extra_path指定额外静态资源
  如果sample文件夹无需Sphinx处理，可直接将其添加到html_extra_path，构建时会完整复制到输出目录。若需要它出现在_static下，保持sample在_static内后，在conf.py中添加：

  html_extra_path = ['_static/sample']
  

• 检查排除规则
  查看conf.py中的exclude_patterns，确保_static/sample未被加入排除列表，避免Sphinx跳过该文件夹。

• 自定义主题中显式声明静态资源
  若你在开发自定义主题，可在主题的__init__.py的setup函数中，通过add_static_file方法指定要复制的文件夹：

  def setup(app):
      app.add_static_file('sample', '_static/sample')
  

  第一个参数是输出到_static下的目录名，第二个是主题内的源路径。

• 清理缓存后重新构建
  Sphinx的缓存可能导致新增文件夹未被检测到，先删除_build目录，再重新执行构建命令：

  rm -rf _build
  sphinx-build -b html docs _build/html
  

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