在 Linux 上为加载 pywin32 的包创建 Sphinx autodoc

Question

我写了一个 package，它使用 pywin32 将 GitLab 问题与 Microsoft Projects 同步。

我想使用 readthedocs 来托管文档。

问题是我无法安装 pywin32，因为那里使用了 Linux 环境。

如果包在构建机器上不可用，关于如何获取autodoc构建文档的任何建议？

Answer 1

我找到了一个或多或少丑陋的解决方案：模拟使用的模块和函数。

需要相当多的手动工作。在您的项目中创建一个 mocking 文件夹，并为每个使用的 class/function 创建模块、类和函数存根。

在此之后编辑 doc/conf.py 并添加：

try:
    import win32com
except ImportError:
    sys.path.insert(0, os.path.join(__location__, '../mocking'))

在真实包不可用时自动加载模拟（并且只有在那时！）。

尽管如此解决方案非常麻烦，但它有一个优点。它允许静态类型，没有它就不可能。

Answer 2

解决这个问题最简单的方法是设置autodoc_mock_imports = ["pywin32"]。这只需要设置根包，您的代码对库的任何后续使用（调用或导入子模块、类等）都将被 Sphinx 模拟。

请注意，模拟库除了允许声明和导入其组件外不会提供任何功能。因此，您的代码应该被构造为没有任何模块级执行取决于 pywin32 可调用对象，因为这些可调用对象的 returns 也将被模拟。

我还发现 this guide that elaborates focused on ReadTheDocs builds and it suggests the same. Parallel to this problem I found the extension sphinxcontrib-mockautodoc 解决了在给定项目中同时具有不同 Python 版本时进行构建的问题。

在 Linux 上为加载 pywin32 的包创建 Sphinx autodoc

Create Sphinx autodoc for a package loading pywin32 on Linux

linux

pywin32

mocking

python-sphinx

autodoc