sphinx-apidoc的--templatedir选项未按预期生效，求助解决方案

问题描述 #

我尝试自定义./docs/conf.py以简化文档管理，执行命令：

sphinx-apidoc -F -o "./docs" --templatedir=./templates "."

并在./templates目录放置了conf.py_t模板文件，但--templatedir选项未按预期生效。每次执行前都会删除./docs目录，但生成的./docs/conf.py与模板文件内容不符，且执行无报错信息。

环境信息 #

• 操作系统：Windows
• 终端：PowerShell
• Python环境：Miniconda 24.1.2、Python 3.12.2
• Sphinx版本：8.1.3

模板与生成文件对比 #

模板文件conf.py_t内容： #

#hogehoge
#hogehoge
#hogehoge
#hogehoge
#hogehoge
#hogehoge
#hogehoge
# Configuration file for the Sphinx documentation builder.
# 
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

import os
import sys
sys.path.insert(0, os.path.abspath('../'))

# -- Project information -----------------------------------------------------

project = '{{ project_name }}'
copyright = '{{ copyright_year }}, {{ author }}'
author = '{{ author }}'

# The full version, including alpha/beta/rc tags
release = '{{ version }}'

# -- General configuration ---------------------------------------------------

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode'
]

templates_path = ['_templates']
exclude_patterns = []

# -- Options for HTML output -------------------------------------------------

html_theme = 'alabaster'
html_static_path = ['_static']

生成的./docs/conf.py内容： #

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'test'
copyright = '2024, Author'
author = 'Author'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.todo',
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

language = 'en'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

# -- Options for todo extension ----------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration

todo_include_todos = True

解决方案 #

1. 检查模板文件路径与命名

   • 确认conf.py_t确实放在./templates目录下，路径无拼写错误。Windows环境下注意路径大小写（虽然Python路径不区分，但Sphinx模板匹配可能严格）。

2. 拆分命令流程
   sphinx-apidoc -F实际是调用sphinx-quickstart生成基础配置，但--templatedir参数可能未正确传递。可以拆分步骤：

   • 先用sphinx-quickstart指定模板生成配置：

     sphinx-quickstart ./docs --templatedir=./templates --sep --project=test --author="Author" --release="0.1"
     

   • 再单独运行sphinx-apidoc生成API文档：

     sphinx-apidoc -o ./docs "."
     

3. 手动替换配置文件
   如果上述方法无效，可先生成默认conf.py，再直接用自定义模板文件覆盖./docs/conf.py，并手动替换模板中的变量（如{{ project_name }}）为实际项目值。

4. 测试Sphinx版本兼容性
   部分Sphinx版本中sphinx-apidoc的--templatedir参数存在bug，可尝试降级到稳定版本（如7.2.6）验证是否解决问题。

5. 确认模板变量有效性
   模板中的变量（如{{ project_name }}）需要在执行命令时通过参数传递，或确保sphinx-quickstart能正确填充这些变量。若未传递参数，变量会保留原样，但当前生成了默认内容，说明模板未被读取，需重点排查路径问题。

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