如何为含连字符的Python项目文件生成Sphinx文档？

问题 #

使用Sphinx生成Python项目文档时，执行make html遇到含连字符的模块（如1-test.py）报错：

WARNING: invalid signature for automodule ('modules.1-test')
WARNING: don't know which module to import for autodocumenting 'modules.1-test' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

对应的.rst文件内容如下：

modules package
================

Submodules
----------

modules.1\ '-\'test module
-------------------------------

.. automodule:: modules.1-test
   :members:
   :undoc-members:
   :show-inheritance:

arrivals.2\`-\`test module
-------------------------

.. automodule:: modules.2-test
   :members:
   :undoc-members:
   :show-inheritance:

不含连字符的模块可正常生成文档，需解决Sphinx对含连字符文件名的支持问题。

解决办法 #

Python原生不支持导入名称含连字符的模块（import modules.1-test会被解析为语法错误），Sphinx的autodoc依赖模块导入，因此需要通过以下方式处理：

方法1：动态导入模块（推荐，可获取完整文档） #

在Sphinx配置文件conf.py中添加代码，通过importlib动态导入目标模块并注册到系统模块列表：

import importlib
import sys

def setup(app):
    # 列出所有含连字符的模块名
    target_modules = ['modules.1-test', 'modules.2-test']
    for module_name in target_modules:
        # 动态导入模块
        module = importlib.import_module(module_name)
        # 将模块加入系统模块字典，让Sphinx能识别
        sys.modules[module_name] = module

方法2：使用Mock导入（仅生成框架文档） #

如果不需要实际导入模块（比如模块依赖未安装的库），可在conf.py中添加Mock配置：

autodoc_mock_imports = ['modules.1-test', 'modules.2-test']

此方法仅能生成模块的基本结构，无法获取成员的详细注释和参数信息。

方法3：修正.rst文件的指令写法 #

同时调整.rst文件的标题和指令，去掉不必要的转义字符，明确指定模块：

modules package
================

Submodules
----------

modules.1-test module
-------------------------------

.. py:module:: modules.1-test
.. automodule:: modules.1-test
   :members:
   :undoc-members:
   :show-inheritance:

modules.2-test module
-------------------------

.. py:module:: modules.2-test
.. automodule:: modules.2-test
   :members:
   :undoc-members:
   :show-inheritance:

注意：此方法需配合方法1的动态导入配置使用，否则仍会报错。

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