conda env creation fails if Python 3 selected

[takluyver]

I put this in readthedocs.yml:

conda:
    file: docs/conda-env.yml
python:
    version: 3
    setup_py_install: true

It creates a conda env with Python 3.5, and then tries to install the standard docs machinery. But docutils is pinned to 0.11, and there isn't a build of this for Python 3.5 (there is a package of docutils 0.12). So I see this failure:

conda install --yes --name docs-build-w-conda sphinx==1.3.1 Pygments==2.0.2 docutils==0.11 mock==1.0.1 pillow==3.0.0 sphinx_rtd_theme==0.1.7 alabaster>=0.7,<0.8,!=0.7.5
Fetching package metadata: /usr/local/lib/python2.7/dist-packages/requests/packages/urllib3/util/ssl_.py:315: SNIMissingWarning: An HTTPS request has been made, but the SNI (Subject Name Indication) extension to TLS is not available on this platform. This may cause the server to present an incorrect TLS certificate, which can cause validation failures. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#snimissingwarning.
  SNIMissingWarning
/usr/local/lib/python2.7/dist-packages/requests/packages/urllib3/util/ssl_.py:120: InsecurePlatformWarning: A true SSLContext object is not available. This prevents urllib3 from configuring SSL appropriately and may cause certain SSL connections to fail. For more information, see https://urllib3.readthedocs.org/en/latest/security.html#insecureplatformwarning.
  InsecurePlatformWarning
....
Solving package specifications: ..
Error: Unsatisfiable package specifications.
Generating hint: 
[                    ]|                                                  |   0%
[2/8                 ]|############                                      |  25%
[3/8                 ]|##################                                |  37%
[5/8                 ]|###############################                   |  62%
[6/8                 ]|#####################################             |  75%
[      COMPLETE      ]|##################################################| 100%



Hint: the following packages conflict with each other:
  - docutils ==0.11
  - python 3.5*

Use 'conda info docutils' etc. to see the dependencies for each package.

The obvious solution is not to pin docutils so it automatically picks the latest version available. If you prefer to keep it pinned, I think that installing dependencies at the same time as you create the environment should work; in this instance, it would fall back to Python 3.4 so it could satisfy the dependencies:

conda create --yes --name docs-build-w-conda python=3 sphinx==1.3.1 Pygments==2.0.2 docutils==0.11 ...

[Carreau]

+1 ing. Same issue.

[ivoflipse]

Wouldn't it be easier to simply provide a RTD-specific environment.yml file, which should include all RTD requirements and possibly a RTD-channel that includes those packages for all (relevant) Python versions.

Then creating the environment for RTD and the package can be done in one fell swoop and these issues would be prevented.

[ericholscher]

You should be able to specify the proper python version in the readthedocs.yml file, eg. version: 3.5

[takluyver]

I'd like it to remain possible to specify python: 3 and get the latest supported version automatically. With conda at least, it should be very easy to support both.

[jakirkham]

So, there are few ways to fix this.

1. conda provides a copy of the docutils package for 0.11 and python 3.5.
2. RTD switches to docutils 0.12, which has a python 3.5 version.
3. pip install the RTD requirements into the conda environment instead.
4. Build a copy of docutils 0.11 on python 3.5 and add it to your own channel.

1 is trivial. I am not sure what constraints there are on RTD, but I would like to think 2 is doable. 3 may have issues. I think I use to have issues doing this so there may still be some. 4 is a reasonable workaround.

[ericholscher]

I just pushed #1947 which I believe will fix this. This creates the initial environment with the environment file, but without specifying any other packages. I believe this means it will depend on you specifying the correct Python environment in your conda environment file, but that seems like a better approach than what we currently have.

Thoughts?