How to use Python 3.5 syntax in readthedocs combined with autodoc?

Question

I would like to generate documentation (including automatically generated documentation with autodoc) for my project using readthedocs.org. However, my project uses Python 3.5 syntax (async and await) and it doesn't look like it can handle that. The build succeeds, although I get a lot of errors like this:

/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):

Is there a way to fix this?

@DietrichEpp: http://docs.readthedocs.org/en/latest/support.html: "If you have questions about how to use Read the Docs, or have an issue that isn’t related to a bug, Stack Overflow is the best place to ask. " :) — Evert Heylen, Mar 21 '16 at 23:32
So you're saying that Stack Overflow is the wrong place then? https://github.com/rtfd/readthedocs.org/issues/1990 — Dietrich Epp, Mar 21 '16 at 23:43

score 4 · Answer 1 · answered Jan 30 '18 at 15:44

The other answers are a bit outdated as nowadays Readthedocs.org does support Python 3.5 and 3.6. To use it one has to configure the readthedocs.yml. Documentation about this can be found here: http://docs.readthedocs.io/en/latest/yaml-config.html.

A minimum example that would make Readthedocs.org use Python 3.5 is:

build:
    image: latest

python:
    version: 3.5

If you have any dependencies, this can be handled via a requirements.txt file or via setup.py. For example if you want to use the setup.py you simply tell Readthedocs.org to install your package:

build:
    image: latest

python:
    version: 3.5
    setup_py_install: true

Just as a note: as of today this feature is still in beta state but seems to work fine. The file's name can be prefixed with a dot: `.readthedocs.yml`. — zezollo, Jun 22 '18 at 06:45

score 2 · Accepted Answer · answered Mar 22 '16 at 00:41

Thanks to Dietrich's answer (my bad for not finding the github issue), I found a very valuable hint about conda. It appears to be somewhat like virtualenv, but it has the power to install binaries and python versions themselves.

I was able to get it working by adding two files to my github repo, both in the root (although environment.yml could go somewhere else). If anyone wants to get a basic conda environment going, you can use this instead of having to install conda yourself.

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

Normally you can add requirements in a requirements.txt file that are then installed through pip. When using conda you have to list them in the environment.yml file, like I already did with momoko, psycopg2 and tornado.

score 1 · Answer 3 · answered Mar 21 '16 at 23:44

1

Readthedocs.org does not currently support Python 3.5, see issue 1990: python 3.5 support for build system.

answered Mar 21 '16 at 23:44

Dietrich Epp

205,541
37
345
415

Oh well, seems I missed that issue. Googling for anything related to 'readthedocs' gives a lot of documentation you're not looking for :) – Evert Heylen Mar 22 '16 at 00:42

How to use Python 3.5 syntax in readthedocs combined with autodoc?

3 Answers3