Problem with autodoc and mocked modules in Python

Viewed 18

We are starting to use the AutoDoc extension for Sphinx, to generate some of our documentation automatically, and we have run into a problem. We have a separate wheel which provides some functionality, a simplified version of which is (in the_module.py):

def get_float():
    return 3.14159

In our code that uses the function, we create a dataclass:

import dataclasses
from the_wheel import the_module

@dataclasses.dataclass
class MyThing:
    my_int: int = 0
    my_float: float = the_module.get_float() - 2.71828  # <- Problematic line on import.

All our builds and various tests are done inside containers at the moment, where everything is available. However, AutoDoc is currently being implemented outside the containers, so we mock the entire module with:

autodoc_mock_imports = ["the_module"]

Unfortunately, when we run autodoc, it complains at the import stage with the message along the lines of:

Unsupported operation between get_float and float.

I suspect that's because the mocked module causes the return value of get_float() to appear as if the type was the function name rather than a float. How do we get around this issue? Specifically:

  • Is there a way to tell AutoDoc that other.getfloat() should be mocked to a float value? That way the expression would be valid.

  • Is there a way to tell AutoDoc to correct the import as it's happening, so that it does not fail?

  • Alternatively, will we be required to run AutoDoc within the same containers as our build system, so that everything is available?

I was hoping that there'd be a solution similar to # pytest: disable=some-problem or # type: ignore[B123] that affects some of our other tools (pytest and mypy). However, I couldn't find anything close to that and there appear to be no AutoDoc options with a sufficient level of specificity.

0 Answers
Related