Create Sphinx autodoc for a package loading pywin32 on Linux

Question

I wrote a package that uses pywin32 to sync GitLab issues with Microsoft Projects.

I would like to use readthedocs to host the documentation.

The problem is that I can't install pywin32 as a Linux environment is used there.

Any suggestion on how to get autodoc to build the documentation if a package is not available on the build machine?

Answer 1

The easiest way to solve this is setting autodoc_mock_imports = ["pywin32"]. This only requires setting the root package and any subsequent use your code makes of the library (calling or importing submodules, classes, etc) will be mocked by Sphinx.

Notice the mocked library won't provide any functionality besides allowing its components to be declared and importable. So your code should be structured to not have any module level execution depending on pywin32 callables, because the returns of those callbles will also be mocked.

I also found this guide that elaborates focused on ReadTheDocs builds and it suggests the same. Parallel to this problem I found the extension sphinxcontrib-mockautodoc that addresses the problem of making builds when you simultaneously have different Python versions in a given project.