如何高效为Python包添加文档？避免流水线二次构建

背景 #

• 开发了Python包DocumentationGenerator，可生成其他Python包的HTML文档，已安装在虚拟环境中。
• 需为SomePythonPackage生成文档，并将文档随包一起构建到最终的.tar.gz文件中，项目使用setuptools作为构建后端，build作为前端，已有流水线负责构建并上传包文件。
• 尝试将DocumentationGenerator的generate_documentation(*args)函数集成到构建脚本中，希望在构建前生成文档，但执行时出现导入错误。

错误详情 #

执行文档生成时触发如下错误：

Importing library 'C:/ProjectPath/src/SomePythonPackage/path/to/lib.py' failed: ModuleNotFoundError: No module named 'SomePythonPackage'
Traceback (most recent call last): File "C:/ProjectPath/src/SomePythonPackage/path/to/lib.py", line 32, in <module>
from SomePythonPackage.subdirectory1.foo import bar

原因是SomePythonPackage内部使用了绝对导入，这种导入方式要求包已被安装，而当前包仅在源码目录，未安装到环境中，导致无法导入。

当前低效解决方案 #

只能先构建不含文档的包→安装该包→生成文档→重新构建包含文档的包，两次构建流程效率低下。

期望的最终包结构 #

生成的.tar.gz解压后需包含如下结构：

SomePythonPackage
|  documentation/...
|  subdirectory1/...
|  subdirectory2/...
|  ...

更新的项目信息 #

项目目录结构 #

ProjectPath/
| .venv/
|  |  ...
|  |  setuptools
|  |  build
|  |  DocumentationGenerator
|  \  ...
| azure-pipelines/
|  \  pipeline.yml
| dist/
|  |  some_python_package.whl
|  \  some_python_package.tar.gz
| src/
|  |  SomePythonPackage/
|  |    |  ...
|  |    |  __init__.py
|  |    |  requirements.txt
|  |    |  doc/... (期望在构建前生成或构建后加入)
|  \    \  ...
| __init__.py
| .gitignore
| MANIFEST.in
| pyproject.toml
| README.md
| setup.py
\ VERSION

核心配置文件内容 #

MANIFEST.in

recursive-include src/SomePythonPackage *
include VERSION
global-exclude .gitignore
global-exclude *.py[cod]

pyproject.toml

[build-system]
requires = ["setuptools>=42"]
build-backend = "setuptools.build_meta"

构建脚本核心代码

if os.path.isdir('C:/ProjectPath/dist'):
    shutil.rmtree('C:/ProjectPath/dist')
subprocess.run([sys.executable, "-m", "build", 'C:/ProjectPath',
               "--outdir", 'C:/ProjectPath/dist'], check=True)

核心疑问 #

寻求无需两次构建的高效方案：

• 是否有办法让Python环境认为SomePythonPackage已安装（无需实际安装包），从而能正常执行文档生成函数？
• 或者有没有可靠的方法在构建完成后，将生成的doc/目录加入到已生成的some_python_package.tar.gz文件中？

内容的提问来源于stack exchange，提问作者Andrew.M