conda support: strict requirements on core dependencies like sphinx 1.3.5 prevent using more recent version

[SylvainCorlay]

The list of core requirements specified at https://github.com/rtfd/readthedocs.org/blob/499a74076f0debae09acc1d4c4eeeab03f8f557e/readthedocs/doc_builder/python_environments.py#L192 prevents requiring another version of sphinx in one's environment.yml.

        # Use conda for requirements it packages
        requirements = [
            'sphinx==1.3.5',
            'Pygments==2.1.1',
            'docutils==0.12',
            'mock',
            'pillow==3.0.0',
            'sphinx_rtd_theme==0.1.7',
            'alabaster>=0.7,<0.8,!=0.7.5',
        ]

For example, if I depend on breathe, which requires sphinx>=1.4.0, this creates a conflict.

[SylvainCorlay]

Example here: https://readthedocs.org/projects/xtensor/builds/4837277/

[humitos]

@ericholscher what about pinning sphinx to 1.5.2 (until conda-forge/sphinx-feedstock#10 got merged) and sphinx_rtd_theme to 0.2.3 (until conda-forge/sphinx_rtd_theme-feedstock#6 got merged)?

I think this will fix a couple of issues with the old versions.

[ericholscher]

Seems reasonable. Will conda properly install from conda-forge in our current setup?

[humitos]

On the other hand, I'm thinking if we really want to have pinned packages in the core conda environment. I mean, I understand that it's needed by the common virtualenv build since RTD offers a way to "just write the docs even if you don't know sphinx or python" (by suggesting you to create the index.rst) but if you are using conda because whatever reason it seems that you are tweaking a couple of stuff and maybe doesn't make sense to have this "core packages pinned at specific versions". It's just a thought and it's not tested in my head :)

[humitos]

Seems reasonable. Will conda properly install from conda-forge in our current setup?

I don't think so, since there is nothing related to the conda-forge channel in the base code and it's not in a default and clean miniconda installation.

[SylvainCorlay]

Why pinning at all?

Just requiring sphinx <=1.5.2 will install 1.5.2 by defaults.

Users will have the freedom to require a more specific version in their environment.yml.

[humitos]

Closgin in favor of #2714