How to make sphinx look for modules in virtualenv while building html?

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 e

Answer 1

The problem is correctly spotted by Mathijs.

$ which sphinx-build
/usr/local/bin/sphinx-build

I solved this issue installing sphinx itself in the virtual environment.

With the environment activated:

$ source /home/migonzalvar/envs/myenvironment/bin/activate
$ pip install sphinx
$ which sphinx-build
/home/migonzalvar/envs/myenvironment/bin/sphinx-build

It seems neat enough.

Answer 2

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.

Answer 3

I had the same problem, but I couldn't use the accepted solution because I didn't use the Makefile. I was calling sphinx-build from within a custom python build file. What I really wanted to do was to call sphinx-build with the exact same environment that I was calling my python build script with. Fiddling with paths was too complicated and error prone, so I ended up with what seems to me like an elegant solution, which is to "manually" load the console script entry point and call it:

from pkg_resources import load_entry_point
cmd = load_entry_point('Sphinx', 'console_scripts', 'sphinx-build')
cmd(['sphinx-build', basepath, destpath])