如何在readthedocs中结合autodoc使用Python 3.5语法？

Question

我希望使用readthedocs.org为我的项目生成文档（包括自动生成的autodoc文档）。然而，我的项目使用Python 3.5语法（async和await），看起来它无法处理。虽然构建成功，但我会遇到很多这样的错误：

/home/docs/checkouts/readthedocs.org/user_builds/sparrow/checkouts/latest/docs/source/entity.rst:176: WARNING: autodoc: failed to import module 'sparrow.entity'; the following exception was raised:
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/sparrow/envs/latest/local/lib/python3.4/site-packages/sphinx/ext/autodoc.py", line 385, in import_object
    __import__(self.modname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/sparrow/checkouts/latest/sparrow/__init__.py", line 26, in <module>
    from .model import *
  File "/home/docs/checkouts/readthedocs.org/user_builds/sparrow/checkouts/latest/sparrow/model.py", line 37
    async def install(self):

有没有办法解决这个问题？

- Evert Heylen

---

你可能想从 readthedocs.org 寻求帮助。 - Dietrich Epp

@DietrichEpp: http://docs.readthedocs.org/en/latest/support.html：“如果您对如何使用Read the Docs有疑问，或者遇到与错误无关的问题，请在Stack Overflow上提问。” :) - Evert Heylen

那么你的意思是Stack Overflow不是正确的地方吗？https://github.com/rtfd/readthedocs.org/issues/1990 - Dietrich Epp

Answer 1

现在Readthedocs.org已经支持Python 3.5和3.6，其他答案有点过时了。要使用它，必须配置readthedocs.yml。可以在这里找到关于此的文档：http://docs.readthedocs.io/en/latest/yaml-config.html。

让Readthedocs.org使用Python 3.5的最小示例为：

build:
    image: latest

python:
    version: 3.5

如果您有任何依赖关系，可以通过一个名为 requirements.txt 或 setup.py 的文件来处理它们。例如，如果您想使用 setup.py，您只需告诉 Readthedocs.org 安装您的软件包即可：

build:
    image: latest

python:
    version: 3.5
    setup_py_install: true

- NOhs

---

仅供参考：截至今天，此功能仍处于测试状态，但似乎可以正常工作。该文件的名称可以以圆点为前缀：.readthedocs.yml。 - zezollo

Answer 2

感谢Dietrich的回答（我没有找到github问题，我的错），我发现了关于conda的非常有价值的提示。它似乎有点像virtualenv，但它有安装二进制文件和Python版本本身的能力。

我通过将两个文件添加到我的github repo中使其工作，这两个文件都在根目录中（尽管environment.yml可以放在其他地方）。如果有人想要获得基本的conda环境，可以使用这个而不是自己安装conda。

readthedocs.yml

conda:
    file: environment.yml

environment.yml

name: py35
dependencies:
- openssl=1.0.2g=0
- pip=8.1.1=py35_0
- python=3.5.1=0
- readline=6.2=2
- setuptools=20.3=py35_0
- sqlite=3.9.2=0
- tk=8.5.18=0
- wheel=0.29.0=py35_0
- xz=5.0.5=1
- zlib=1.2.8=0
- pip:
  - momoko>=2.2.3
  - psycopg2>=2.6.1
  - tornado==4.3

通常，您可以在要求.txt文件中添加要求，然后通过pip安装。当使用conda时，您必须在environment.yml文件中列出它们，就像我已经使用momoko、psycopg2和tornado一样。

- Evert Heylen

Answer 3

Readthedocs.org目前不支持Python 3.5，请参见问题1990：构建系统对Python 3.5的支持。

- Dietrich Epp

---

哦，好吧，看来我错过了那个问题。谷歌搜索与“readthedocs”相关的任何内容都会给你带来很多你不需要的文档 :) - Evert Heylen