How to make sphinx look for modules in virtualenv while building html?
VirtualenvPython SphinxVirtualenv Problem Overview
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)?
Virtualenv Solutions
Solution 1 - Virtualenv
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.
Solution 2 - Virtualenv
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.
Solution 3 - Virtualenv
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])