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](http://matplotlib.org/sampledoc/extensions.html#inserting-
matplotlib-plots)** to generate and embed matplotlib's diagrams on the fly,
and i'm using [ReadTheDocs](https://readthedocs.org) for auto-generating the
project's documentation.  
The plot-directive indeed [works ok in
python-2](https://github.com/rtfd/readthedocs.org/issues/1021), 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](http://read-the-
docs.readthedocs.org/en/latest/faq.html#i-get-import-errors-on-libraries-that-
depend-on-c-modules), 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](https://docs.readthedocs.org/en/latest/builds.html#packages-installed-in-the-build-environment) of pre-installed native libraries on RTD
  * The [actual `pip-requirements.txt`](https://github.com/rtfd/readthedocs.org/blob/master/pip_requirements.txt) file used to setup the build-server, as found from RTD's sources.


Answer: Since today, the problem is officially solved, according to [rtfd issue
#896](https://github.com/rtfd/readthedocs.org/issues/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.

