Docs: poetry example on build.jobs section

[humitos]

There are multiple ways to install Poetry on Read the Docs and all of them have, at least,
one thing that I don't like. So, I'm recommending using the official one
described as the first option in their own page --which is not perfect, but it's
the official one :)

[ericholscher]

This looks reasonable 👍 It's not super clean, but seems to work well enough.

[agjohnson]

I think they suggest this version, but more for local development purposes. For our use case, where we are building a fresh environment every build and Poetry and dependencies will not have a chance to conflict with anything, the pip install method seems totally reasonable.

[humitos]

For our use case, where we are building a fresh environment every build and Poetry and dependencies will not have a chance to conflict with anything, the pip install method seems totally reasonable.

It won't conflict immediately because the environment is fresh, that's true. However, as it was installed in the virtualenv the user is going to use to install their dependencies (note the virtualenvs.create false option), I think there could be issues there since some packages from Poetry itself could be upgrade/downgraded, right?

[humitos]

Mrm... another option could be to install Poetry on pre_create_environment which will use the Python from the system (not the virtualenv) and then use post_create_environment to install the dependencies? How do we tell Poetry to install the dependencies inside the virtualenv it's not running from then? 🤔

[agjohnson]

Ah good point. I don't have any strong objections here, I've just found that the pip install method works fine for me. I'm sure we'll get some conflicting advice from Poetry users here soon either way -- seemed that there were some opinions on this pattern.

How do we tell Poetry to install the dependencies inside the virtualenv it's not running from then?

I think I get what you're saying. Wouldn't this be the same case for the curl installed method, which is just packaged up away from the system/venvs? I don't know the answer to your question, but your suggestion sounds reasonable.

[humitos]

Mrm... another option could be to install Poetry on pre_create_environment which will use the Python from the system (not the virtualenv) and then use post_create_environment to install the dependencies?

I tested this and it didn't work: https://readthedocs.org/projects/test-builds/builds/17527514/. I tried to do some other tests locally and I'm not exactly sure how poetry internals work, but also I'm not sure it's worth going too deep into this either. I prefer to recommend the official way to install it than the not recommended by themselves because it looks nicer but introduce our users to random issues that we are not aware right now.

[humitos]

We can always update this example if we find there is a better and supported way of doing this.

[davidorme]

@humitos - apologies for resurrecting this PR, it seemed like a natural place to post this and I couldn't see any more recent issues about poetry and installing.

I'm trying to build a site for a package managed using poetry and following the officially documented approach in the build.jobs docs section. That approach now appears to be failing:

https://readthedocs.org/projects/virtual-rainforest/builds/18663328/

The TLDR on that build log error is that the old get-poetry.py install will not install recent versions (>1.2.0a1) and that the new https://install.python-poetry.org approach must be used instead. I tried using that approach:

build:
  os: ubuntu-20.04
  tools:
    python: "3.9"
  jobs:
    post_create_environment:
      # Install poetry
      - curl -sSL https://install.python-poetry.org | python3 -
      # Tell poetry to not use a virtual environment
      - $HOME/.local/bin/poetry config virtualenvs.create false
      # Install project's dependencies
      - $HOME/.local/bin/poetry install

but that doesn't seem to be working: https://readthedocs.org/projects/virtual-rainforest/builds/18663177/

I know that is an apparent error in my package, but it doesn't occur with local sphinx builds and seems like a problem with the installed environment?

[agjohnson]

Hi @davidorme! Thanks for the update on the install method, we should probably note that in our docs. Care to open this up as a new issue instead?