How can i use matplotlib's plot-directive with python-3 in ReadTheDocs?

Question

I'm having a python-3 project that uses the plot-directive to generate and embed matplotlib's diagrams on the fly, and i'm using ReadTheDocs for auto-generating the project's documentation.
The plot-directive indeed works ok in python-2, but it currently fails in python-3.

Specifically the failure i'm getting on the logs of RTD is this:

Build Standard Error

html
-----

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", line 325, in setup_extension
    mod = __import__(extension, None, None, ['setup'])
ImportError: No module named 'matplotlib'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/cmdline.py", line 253, in main
    warningiserror, tags, verbosity, parallel)
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", line 119, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/wltp/envs/master/lib/python3.4/site-packages/sphinx/application.py", line 328, in setup_extension
    err)
sphinx.errors.ExtensionError: Could not import extension matplotlib.sphinxext.plot_directive (exception: No module named 'matplotlib')

Extension error:
Could not import extension matplotlib.sphinxext.plot_directive (exception: No module named 'matplotlib')

And the culprit can be traced to matplotlib not being compiled due to mnissing 'freetype' C lib:

Setup Output

...

requirements
-----
...
BUILDING MATPLOTLIB
            matplotlib: yes [1.4.2]
                python: yes [3.4.0 (default, Apr 11 2014, 13:05:11)  [GCC
                        4.8.2]]
              platform: yes [linux]

REQUIRED DEPENDENCIES AND EXTENSIONS
                 numpy: yes [not found. pip may install it below.]
                   six: yes [six was not found.]
              dateutil: yes [dateutil was not found. It is required for date
                        axis support. pip/easy_install may attempt to
                        install it after matplotlib.]
                  pytz: yes [pytz was not found. pip will attempt to install
                        it after matplotlib.]
               tornado: yes [tornado was not found. It is required for the
                        WebAgg backend. pip/easy_install may attempt to
                        install it after matplotlib.]
             pyparsing: yes [pyparsing was not found. It is required for
                        mathtext support. pip/easy_install may attempt to
                        install it after matplotlib.]
                 pycxx: yes [Official versions of PyCXX are not compatible
                        with matplotlib on Python 3.x, since they lack
                        support for the buffer object.  Using local copy]
                libagg: yes [pkg-config information for 'libagg' could not
                        be found. Using local copy.]
              freetype: no  [The C/C++ header for freetype2 (ft2build.h)
                        could not be found.  You may need to install the
                        development package.]    
    OPTIONAL LATEX DEPENDENCIES
                dvipng: yes [version 1.14]
           ghostscript: yes [version 9.10]
                 latex: yes [version 3.1415926]
               pdftops: no

============================================================================
                        * The following required packages can not be built:
                        * freetype

To make the doc-generation pass, I'm forced to "disable" plot-directive by mocking it out, as instructed in the RTD FAQ, using the following code in the ./conf.py file.

I've tried with various combinations of virtualenv (with or without site-package visibility), rtd-specific requirements.txt, with no success.

Has anybody found a way to do it?

These are some hints for those willing to dig further into the issue:

• The "official" list of pre-installed native libraries on RTD
• The actual pip-requirements.txt file used to setup the build-server, as found from RTD's sources.

Answer 1

Since today, the problem is officially solved, according to rtfd issue #896. All required dependencies (matplotlib, scipy and numpy) are also installed for python-3, so mocking is not necessary anymore.

To make use of it, in the Advanced settings make the following choices:

• Check: Install Project: Install your project inside a virtualenv using setup.py install
• Select: Python interpreter: CPython 3.x
• Check: Use system packages: Give the virtual environment access to the global site-packages dir.

...although with a little training, it is easy to write python-2/3 compatible code.