search

OpenNTI / sphinxcontrib-programoutput

Sphinx extension for capturing program output
BSD 3-Clause "New" or "Revised" License
37 stars 17 forks source link

automock compatibility #54

Closed kousu closed 3 years ago

kousu commented 3 years ago

I am in the same situation as https://github.com/readthedocs/readthedocs.org/issues/5512: I want to run sphinx on readthedocs without having to install the entire 600MB of dependencies that my project needs.

I am using autodoc_mock_imports to avoid having to install my dependencies just for docs:

https://github.com/neuropoly/spinalcordtoolbox/blob/67a2bdb378344a4cef828b23ba7af0debd20b8d9/documentation/source/conf.py#L50

but I'm also using program-output:: and the mocks don't reach past it, so the build fails. Is there some special flag I can pass to python to get program-output:: to pick up the mocks too?

Like, can I do:

program-output:: SPHINX_AUTOMOCK=1 python -c my_tool.py -h

?

jamadden commented 3 years ago

Is there some special flag I can pass to python to get program-output:: to pick up the mocks too?

program-output runs any arbitrary executable as a brand new program, and autodoc_mock_imports is specific to the original running Python process. Everything autodoc_mock_imports does is in the memory of that one process only; there's no way to communicate that to the brand new process (moreover, program-output has no idea that the child process should in any way be related to the parent process). Someone would need to modify autodoc_mock_imports to either:

  1. Create persistent mock files on disk and modify the PYTHONPATH environment variable for child processes; or
  2. Somehow figure out how to modify sys.meta_path in the child process to do the same thing autodoc_mock_imports is doing; this means both a. figuring out how to always automatically execute code to edit sys.meta_path as there is no environment variable support for that (so messing around with things like sitecustomize.py or .pth files); and b. communicating the list of mocked modules somehow

It's an interesting challenge, but not one that this package can solve on its own.

kousu commented 3 years ago

Thanks for thinking it through @jamadden. That's about the conclusion I was coming to as well.

I'm going to give https://github.com/sphinx-contrib/autoprogram/ or https://sphinx-argparse.readthedocs.io/en/stable/ a shot. Those should be running in the same python process so maybe the mocks will work there.

Thanks for your time!