Question

I want to build html docs using a virtualenv instead of the native environment on my machine.

I’ve entered the virtualenv but when I run make html I get errors saying the module can’t be imported – I know the errors are due to the module being unavailable in my native environment.
How can I specify which environment should be used when searching for docs (eg the virtualenv)?

Answer 1

The problem here is that make html uses the sphinx-build command as a normal shell command, which explicitly specifies which Python interpreter to use in the first line of the file (ie. #!/usr/bin/python). If Python gets invoked in this way, it will not use your virtual environment.

A quick and dirty way around this is by explicitly calling the sphinx-build Python script from an interpreter. In the Makefile, this can be achieved by changing SPHINXBUILD to the following:

SPHINXBUILD   = python <absolute_path_to_sphinx-build-file>/sphinx-build

If you do not want to modify your Makefile you can also pass this parameter from the command line, as follows:

make html SPHINXBUILD='python <path_to_sphinx>/sphinx-build'

Now if you execute make build from within your VirtualEnv environment, it should use the Python interpreter from within your environment and you should see Sphinx finding all the goodies it requires.

I am well aware that this is not a neat solution, as a Makefile like this should not assume any specific location for the sphinx-build file, so any suggestions for a more suitable solution are warmly welcomed.