Installing an extension from conf.py

Question

I try to build the docs, and use a custom sphinx extension, but this extension isn't installed by default - so I provide it via conf.py, using this:

try:
    import sphinxjp.themes
except ImportError:
    from setuptools.command import easy_install
    easy_install.main( ["-U","sphinxjp.themes.basicstrap"] )
    import sphinxjp.themes

extensions += ['sphinxjp.themes.basicstrap']
html_theme = 'basicstrap'

html_theme_options = {
  'bootstrap_version': '3',
  'noresponsive': False,
  'inner_theme': True,
  'inner_theme_name': 'bootswatch-yeti',
}

But the problem is as follows:

1. Python installs the extension if it is not found, or skips if it exists.
2. But here, if it didn't exist, python will install it, and continue the execution of the file as if it didn't install it.
3. I have then to run the file again so python can skip the installation process and build the docs.

How do I force python to load the extension just after it is installed?

I get this error:

Running Sphinx v1.3b2
Searching for sphinxjp.themes.basicstrap
Reading https://pypi.python.org/simple/sphinxjp.themes.basicstrap/
Best match: sphinxjp.themes.basicstrap 0.4.1
Downloading https://pypi.python.org/packages/source/s/sphinxjp.themes.basicstrap
/sphinxjp.themes.basicstrap-0.4.1.tar.gz#md5=bac7d878391a3dfd663b51e2311d5795
Processing sphinxjp.themes.basicstrap-0.4.1.tar.gz
Writing c:\users\abdelo~1\appdata\local\temp\easy_install-ndzj8s\sphinxjp.themes
.basicstrap-0.4.1\setup.cfg
Running sphinxjp.themes.basicstrap-0.4.1\setup.py -q bdist_egg --dist-dir c:\use
rs\abdelo~1\appdata\local\temp\easy_install-ndzj8s\sphinxjp.themes.basicstrap-0.
4.1\egg-dist-tmp-pdyuqk
Adding sphinxjp.themes.basicstrap 0.4.1 to easy-install.pth file

Installed c:\python27\lib\site-packages\sphinxjp.themes.basicstrap-0.4.1-py2.7.e
gg
Processing dependencies for sphinxjp.themes.basicstrap
Finished processing dependencies for sphinxjp.themes.basicstrap

Exception occurred:
  File "conf.py", line 11, in <module>
    import sphinxjp.themes
ImportError: No module named sphinxjp.themes
The full traceback has been saved in c:\users\abdelo~1\appdata\local\temp\sphinx
-err-wzgl0z.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message c
an be provided next time.
A bug report can be filed in the tracker at <https://bitbucket.org/birkenfeld/sp
hinx/issues/>. Thanks!

And as you can see, the extension has been installed! So I have to run it a second time so that it will work.

Answer 1

When the extension is installed, it creates a .pth file, which would normally be processed during initialization when site.py is imported. Amongst other things, the .pth file specifies additional items that must be added to sys.path so that the new extension can be imported.

Your script therefore needs to take steps to explicitly process the .pth file after it is installed. One way to do this is to use the pkg_resources module which is part of setuptools:

try:
    import sphinxjp.themes
except ImportError:
    from pkg_resources import get_distribution
    from setuptools.command import easy_install
    easy_install.main( ["-U","sphinxjp.themes.basicstrap"] )
    get_distribution('sphinxjp.themes.basicstrap').activate()
    import sphinxjp.themes