Sphinx autodoc on readthedocs: ImportError: No module named _tkinter

Question

I'm trying to build documentation on https://readthedocs.org/.

I cannot see the docstrings for any files that import matplotlib.

When I look into the build log, I see that from matplotlib import pyplot as plt failed, with the message:

/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/checkouts/latest/docs/source/plotting.rst:67: WARNING: autodoc: failed to import function u'dbplot' from module u'artemis.plotting.db_plotting'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 551, in import_object
    __import__(self.modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/artemis_ml-1.6-py2.7.egg/artemis/plotting/db_plotting.py", line 3, in <module>
    from artemis.plotting.matplotlib_backend import BarPlot
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/artemis_ml-1.6-py2.7.egg/artemis/plotting/matplotlib_backend.py", line 7, in <module>
    from matplotlib import pyplot as plt
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/matplotlib/pyplot.py", line 115, in <module>
    _backend_mod, new_figure_manager, draw_if_interactive, _show = pylab_setup()
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/matplotlib/backends/__init__.py", line 32, in pylab_setup
    globals(),locals(),[backend_name],0)
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/matplotlib/backends/backend_tkagg.py", line 6, in <module>
    from six.moves import tkinter as Tk
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/six.py", line 203, in load_module
    mod = mod._resolve()
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/six.py", line 115, in _resolve
    return _import_module(self.mod)
  File "/home/docs/checkouts/readthedocs.org/user_builds/artemis-ml/envs/latest/lib/python2.7/site-packages/six.py", line 82, in _import_module
    __import__(name)
  File "/home/docs/.pyenv/versions/2.7.13/lib/python2.7/lib-tk/Tkinter.py", line 39, in <module>
    import _tkinter # If this fails your Python may not be configured for Tk
ImportError: No module named _tkinter

I've already specified (in the readthedocs Admin>Advanced Settings) page so that:

• The project should be build in a virtualenv
• The project should build using the requirements.txt file which includes matplotlib. You can also see that it's been installed from the above message - just not correctly apparently.

Anyone ran into this before and know how to fix it?

The answers in Tkinter: "Python may not be configured for Tk" do not help as this is about readthedocs.

Answer 1

You can solve this problem with a mock import.

Sphinx provides this features to autogenerate docs as decribed here. Simply write at the beginning of your conf.py

autodoc_mock_imports = ['_tkinter']

There is an example here: https://github.com/scopus-api/scopus/blob/4bb7f62f7a94e652f77515c94e7e0bab0d07cce7/docs/conf.py#L24

Answer 2

MERose's solution is probably the best, but in case it doesn't work here is another workaround that worked for me:

You can just make sphinx use import matplotlib with the 'agg' backend, which does not require tkinter, by opening <project root>/docs/source/conf.py and inserting the lines:

import matplotlib
matplotlib.use('agg')

At the end.