2

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?

bad_coder
  • 11,289
  • 20
  • 44
  • 72
Kound
  • 1,835
  • 1
  • 17
  • 30

2 Answers2

2

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.

bad_coder
  • 11,289
  • 20
  • 44
  • 72
1

I found a more or less ugly solution: Mocking the used modules and functions.

Needs quite some manual work. Create a mocking folder in your project and create modules, classes and function stub for each class/function used.

After this edit the doc/conf.py and add:

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

to automatically load the mocking if the real package is not available (and only then!).

Even so the solution is quite cumbersome it has one advantage. It allows for static typing, that would not be possible without.

Kound
  • 1,835
  • 1
  • 17
  • 30
  • If there is a solution required less manual work or nor mocking at all I will accept it. – Kound Nov 14 '20 at 23:08
  • I understand the problem but I'm not experienced enough with RTD to know an exact solution for this case. From my Sphinx experience using [`autodoc_mock_imports`](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports) shouldn't require replicating anything, just naming the root package `pywin32` should be enough. [This guide](https://brendanhasz.github.io/2019/01/05/sphinx.html#mock-importing-packages) elaborates focused on RTD builds and seems to suggest the same. Maybe [this extension](https://pypi.org/project/sphinxcontrib-mockautodoc/). – bad_coder Nov 15 '20 at 01:31
  • Seems to work pretty well. Would you care to add an answer, so I can mark it as valid answer? Thanks :) – Kound Nov 15 '20 at 14:38