YML Configuration File Does Not Change Build Python Version

[kb1lqc]

Details

A local Docker image built with the following Dockerfile results in builds that fail.

FROM python:3.6-stretch

# Update the package repository
RUN apt-get update && apt-get upgrade -y

RUN apt-get install -y git>=2.17.0
RUN apt-get install -y python-pip>=1.5
RUN apt-get install -y redis-server
RUN apt-get install -y wget
RUN apt-get install -y dpkg
RUN apt-get install -y build-essential
RUN apt-get install -y python-dev python-pip python-setuptools
RUN apt-get install -y libxml2-dev libxslt1-dev zlib1g-dev

# Install elasticsearch
RUN wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.2.0-amd64.deb
RUN wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-7.2.0-amd64.deb.sha512
RUN shasum -a 512 -c elasticsearch-7.2.0-amd64.deb.sha512 
RUN dpkg -i elasticsearch-7.2.0-amd64.deb

RUN mkdir checkouts
WORKDIR checkouts
RUN git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org.git
WORKDIR readthedocs.org
RUN pip install -r requirements.txt

RUN python ./manage.py migrate
RUN echo "from django.contrib.auth.models import User; User.objects.create_superuser('admin', 'admin@localhost', 'admin')" | python ./manage.py shell
COPY .readthedocs.yml .readthedocs.yml
COPY local_settings.py readthedocs/settings/local_settings.py

# Load test data
RUN python ./manage.py loaddata test_data

# Move Django app files to central location
RUN python ./manage.py collectstatic

CMD ["python", "./manage.py", "runserver", "0.0.0.0:8000"]

The .readthedocs.yml file that is copied onto the server includes a simple:

# .readthedocs.yml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Optionally build your docs in additional formats such as PDF and ePub
formats: all

build:
    image: latest

# Optionally set the version of Python and requirements required to build your docs
python:
    version: 3.6
    install:
    - requirements: docs/requirements.txt
    - requirements: requirements.txt

Finally, the local_settings.py file that is copied includes:

PRODUCTION_DOMAIN: "localhost:8000"
PUBLIC_DOMAIN_USES_HTTPS = True

I have confirmed that the two files are placed correctly with .readthedocs.yml in the root folder of the git repository and local_settings.py in readthedocs/settings/.

• Read the Docs project URL: None
• Build URL (if applicable): None
• Read the Docs username (if applicable):

Expected Result

I expect the build to work and force Python 3.6 to work since #5335 clearly states to do this as a workaround the the Python 3.7 issues the current Read The Docs release has. This clearly appears not to be working as the build still tries to use Python 3.7.

Actual Result

python3.7 -mvirtualenv --no-site-packages --no-download

/checkouts/readthedocs.org/user_builds/pip/envs/0.8.1
Traceback (most recent call last):
  File "/checkouts/readthedocs.org/readthedocs/doc_builder/environments.py", line 183, in run
    env=environment,
  File "/usr/local/lib/python3.6/subprocess.py", line 729, in __init__
    restore_signals, start_new_session)
  File "/usr/local/lib/python3.6/subprocess.py", line 1364, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
FileNotFoundError: [Errno 2] No such file or directory: 'python3.7': 'python3.7'

[stsewd]

Hi @kb1lqc how are you building your project?

The project that you are building should have the configuration file https://docs.readthedocs.io/en/stable/config-file/index.html (not the Read the Docs source code). Read the Docs defaults to 3.7.

Also, the rtd core team doesn't give support for local installations, please see https://docs.readthedocs.io/en/stable/open-source-philosophy.html

[stsewd]

Also, the Read the Docs code is the one that has the restriction of python 3.6. The projects that are build with read the docs can use any other python version (but your local environment should have those python versions)

[kb1lqc]

@stsewd Thanks for the response. I am commenting that it appears the configuration file does nothing and isn't read. I followed the instructions at https://docs.readthedocs.io/en/stable/config-file/index.html and the build still tries to use Python 3.7 even though I'm clearly specifying 3.6.

[kb1lqc]

By build do you mean docker build or RTD build?

[kb1lqc]

Oh @stsewd that configuration file needs to be in the project your importing not in the git repo of readthedocs.org... that actually wasn't super obvious in retrospect. OK then why does this fail if I follow the instructions at https://docs.readthedocs.io/en/stable/development/install.html as it wants Python 3.7 but the documention makes absolutely no mention of Python 3.7 and just says in needs Python 3.6. This seems to be a mistake in the documentation.

[stsewd]

If you want to build with other python version, you should have those installed, you can use pyenv to have multiple python version in your system. There is quick mention of that in https://docs.readthedocs.io/en/stable/development/install.html#requirements

If you plan to import Python 2 projects to your RTD, then you’ll need to install Python 2 with virtualenv in your system as well.

Feel free to update the guide to mention the other python versions.
Closing, as this was a misunderstanding of the usage of the readthedocs.yml file.

[kb1lqc]

@stsewd yes the original question was a misunderstanding of the readthedocs.yml though I do believe the installation instructions are broken as following them and building one of the sample projects (readthedocs.org) simply breaks because Python 3.7 isn't available.

[stsewd]

Opened #5908