如何在多个GitHub仓库中共享Sphinx文档主题？

核心思路：将主题封装为可复用Python包 #

把自定义Sphinx主题（含基础主题配置、自定义CSS）打包成独立Python包，让所有扩展仓库通过依赖安装统一引入，彻底消除重复配置和逐个维护的繁琐。

具体操作步骤 #

• 搭建主题独立仓库
  遵循Sphinx主题规范组织结构：
  • 根目录下创建theme.conf（主题核心配置文件）
  • 新建static文件夹存放自定义CSS、JS资源
  • 若需自定义页面模板，添加templates文件夹
    编写pyproject.toml（或setup.py）将其打包为Python包，命名可参考sphinx-tket-theme。
• 发布主题包
  将包发布到PyPI（公开项目）或内部私有仓库，确保所有扩展仓库能便捷安装。
• 统一扩展仓库配置
  在每个扩展仓库的docs/conf.py中替换原主题配置：

  import sphinx_tket_theme
  html_theme = "sphinx_tket_theme"
  html_theme_path = [sphinx_tket_theme.get_html_theme_path()]
  # 若主题包已包含自定义CSS，无需额外配置；如需扩展可在此添加
  # html_css_files = ["extra-custom.css"]
  

  同时在仓库的文档依赖文件（如requirements-docs.txt或pyproject.toml）中添加sphinx-tket-theme并指定版本，确保所有仓库使用一致的主题版本。

后续维护优化 #

• 版本化管理：主题更新时发布新版本，各扩展仓库仅需升级依赖版本即可同步变更，无需修改conf.py。
• CI/CD协同：在主题仓库配置自动化测试，验证主题变更不会破坏文档构建；各扩展仓库的CI流程自动拉取指定版本的主题依赖进行构建。
• 备选方案（不推荐）：若不想发布PyPI包，可将主题仓库作为Git子模块嵌入各扩展仓库的docs/_themes目录，但这种方式依赖Git操作，易出现子模块版本不一致，维护成本仍较高。

额外优化建议 #

• 在主题包中封装通用Sphinx配置（如文档结构、启用的扩展、自定义HTML模板），让各扩展仓库的conf.py只需导入通用配置，进一步减少重复代码。
• 创建文档模板仓库，包含标准化的docs目录结构、conf.py模板、CI配置模板，新扩展仓库直接复用模板，从源头统一文档配置。

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