如何在 ReadTheDocs 中将 matplotlib 的绘图指令与 python-3 一起使用？

Question

我有一个 python-3 项目，它使用 plot-directive 动态生成和嵌入 matplotlib 的图表，我正在使用 ReadTheDocs用于自动生成项目的文档。
plot-directive 确实是 works ok in python-2，但它目前在 python-3 中失败。

具体来说，我在 RTD 日志中遇到的故障是：

构建标准错误

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')

而罪魁祸首可以追溯到 matplotlib 由于 mnissing 'freetype' C lib 没有被编译：

设置输出

...

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

为了使文档生成通过，我不得不通过使用./conf.py 文件中的以下代码将其模拟为instructed in the RTD FAQ 来“禁用”绘图指令。

我尝试了virtualenv（有或没有站点包可见性）、特定于 rtd 的requirements.txt 的各种组合，但没有成功。

有人找到方法了吗？

这些是对那些愿意深入研究这个问题的人的一些提示：

• RTD 上预装本机库的"official" list
• actual pip-requirements.txt 文件用于设置构建服务器，可从 RTD 的源代码中找到。

Answer 1

从今天开始，问题正式解决，据rtfd issue #896。 还为 python-3 安装了所有必需的依赖项（matplotlib、scipy 和 numpy），因此不再需要模拟。

要使用它，请在Advanced settings 中做出以下选择：

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

...虽然稍加训练，但编写python-2/3兼容的代码还是很容易的。

Answer 2

我有同样的问题，它似乎与 RTD 解释器有关。我的项目在 Python 3 中，我在 RTD 设置中选择了很多，但它失败了（找不到 matplotlib）。我可以通过选择 Python 2.x 解释器（在高级设置中；也允许全局站点包）来解决它，而不是 Python 3.x。我使用了一个特定于 RTD 的需求文件（它只包含我在全球站点包之外需要的东西：sphinxcontrib-napoleon）。现在可以看到 Matplotlib，但现在我遇到了 Python 2 向后兼容性的问题。但至少这个问题已经解决了。