Readthedocs.org: allow specifying extras instead of requirements.txt

[davidism]

Our projects rely on setup.py instead of requirements.txt for specifying requirements. I'd like to be able to add an extras_require named "docs" and tell RTD about it so that it can do pip install .[docs] when building, instead of creating a separate docs-require.txt file.

[ericholscher]

Believe this will do it: http://docs.readthedocs.io/en/latest/yaml-config.html#python-extra-requirements

[davidism]

That can work, I was thinking of trying out the YAML support. How does this work when building multiple versions? Does each tag need the YAML file or is it always pulled from master?

I still think it would be convenient to have a web interface for this.

[humitos]

That can work, I was thinking of trying out the YAML support. How does this work when building multiple versions? Does each tag need the YAML file or is it always pulled from master?

Each tag will have its own yaml version file with its specific settings.

As a general rule (although, it's not 100% strict yet), we are having "global settings" (those that affect all the builds/versions) under the web admin interface and "version specific settings" on the YAML file.

[davidism]

That won't work for us. We want to build docs for old versions, but we've already released those tags, we don't usually go back and add new commits / releases just for docs. This is the same motivation for #3483. So I'd definitely like to see a global interface for this.

[davidfischer]

I thought you weren't going to building off of tags but rather branches. Taking flask's branches for example, you would just have to commit a readthedocs.yml to master and cherry pick it to the other two branches. Or do I have this wrong and you were going to build from tags?

python:
   pip_install: true
   extra_requirements:
       - docs

[davidism]

Wasn't sure if it would be possible to do the branches, so wanted to cover the tag case as well. If what we want to do with branches will work, then I'm fine using the YAML config for specifying requirements.

[davidfischer]

It is definitely possible to do branches. For Flask for example, you'd go to https://readthedocs.org/projects/flask/versions/ and set the branches you want to build.

There are still some other complications building Flask's docs which I'm working on. Flask's conf.py sets data into the html_context['versions'] variable which has a naming conflict with us. I think the best way to resolve that is to actually implement @humitos' proposals in https://github.com/rtfd/readthedocs.org/pull/3490.

[humitos]

There are still some other complications building Flask's docs which I'm working on. Flask's conf.py sets data into the html_context['versions'] variable which has a naming conflict with us. I think the best way to resolve that is to actually implement @humitos' proposals in #3490.

We discussed this yesterday and since it may take us some time to do it as a general solution, we wanted to have a quicker and simple solution to don't break on this case. @davidfischer opened the PR #4349 that will make your project to not interferes with the RTD context data. Once merged, we will need to know all the projects that use the pallets theme to add this feature to them.

[davidism]

Actually, Flask's conf shouldn't be setting versions, that was a leftover from some testing I was doing. However, RTD still shouldn't set versions, because the Pallets theme checks for that key and expects a certain format.

[davidfischer]

I think the short term fix is https://github.com/rtfd/readthedocs.org/pull/4349.

The longer term fix will be to implement https://docs.readthedocs.io/en/latest/design/theme-context.html

[davidism]

That's fine, I can make that work.