如何配置Hatch实现sphinxcontrib命名空间包正确安装？

在sphinxcontrib组织语境下，所有包必须置于sphinxcontrib命名空间包中（如sphinxcontrib.icon、sphinxcontrib.badge）。现有文件结构如下：

sphinxcontrib-icon/
├── sphinxcontrib/
│   └── icon/
│       └── __init__.py
└── pyproject.toml 

原基于setuptools的pyproject.toml配置可正常工作：

# pyproject.toml

[build-system]
requires = ["setuptools>=61.2", "wheel", "pynpm>=0.2.0"]
build-backend = "setuptools.build_meta"

[tool.setuptools]
include-package-data = false
packages = ["sphinxcontrib.icon"]

迁移至Hatch后，当前配置无法复现预期效果：

# pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["sphinxcontrib/skeleton"]

安装后site-packages目录未出现预期的sphinxcontrib/icon结构，导致执行nox -s docs构建文档失败。

解决步骤 #

1. 修正pyproject.toml配置

Hatch需要显式启用命名空间包支持，同时包路径要匹配实际目录结构。修改后的配置如下：

# pyproject.toml

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.hatch.build.targets.wheel]
packages = ["sphinxcontrib/icon"]
namespace-packages = ["sphinxcontrib"]

2. 确保sphinxcontrib为命名空间包

在sphinxcontrib/目录下添加__init__.py文件（Python 3.3+支持隐式命名空间，但显式声明更稳妥）：

# sphinxcontrib/__init__.py
__import__('pkg_resources').declare_namespace(__name__)

如果使用纯隐式命名空间包，也可以让这个文件为空，但必须保证sphinxcontrib目录存在。

3. 验证构建与安装

执行构建命令：

hatch build

安装生成的wheel包后，检查site-packages目录，确认sphinxcontrib/icon结构已正确生成。

原因说明 #

Setuptools会自动识别sphinxcontrib.icon这种写法对应的命名空间关系，但Hatch需要通过namespace-packages选项显式开启共享命名空间支持，同时包路径需用斜杠对应实际目录层级，才能正确生成符合预期的目录结构。

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