Confusing documentation when using Poetry with ReadTheDocs

[juantocamidokura]

Current user experience

There are 2 pages on ReadTheDocs documentation that explains how to install dependencies using Poetry build system:

1. A whole page that installs the dependencies through Pip
2. A config snippet that uses the build customization feature with Poetry

The Poetry user experience when reading the documentation is a bit confusing as both pages give different approaches.

According to #9743 (comment), the first page was written a long time ago and it's outdated. Furthermore, it doesn't follow the Poetry zen as it uses extras instead of dependency groups to install development packages.

However, the second page uses dependency groups which follows good practices guidelines from Poetry. However, as it is not natively supported as is the case with Conda or Pip build systems, it feels hacky to work with it.

Proposed solutions

• Remove the misleading page entirely and rely on the config snippet to document Poetry use case
• Update the page with good Poetry practices, expanding on the config snippet provided at Docs: update instructions to install deps with Poetry #9743
• Add a Poetry python.install.method that would abstract the config snippet. This option would require a separate issue if it's seen as a desirable feature request

[humitos]

Thanks for opening this issue, @juantocamidokura!

As I mentioned in other issues, I'm not a Poetry user, so my opinion may be biased 😄 . I'd say we should remove the conflicting page since it's old and you mentioned it does not follow good Poetry practices and update the snippet with the required changes, if any.

I think we won't add Poetry as an installation method in python.install.method because the work required to natively support it is huge (see #4912) and it's not currently a blocker for our users: you can still use Poetry on Read the Docs by using the snippet which is 👍🏼 . You also have 100% control about how to install your dependencies and we don't need to implement all the arguments that users may want to pass to Poetry itself.

Update the page with good Poetry practices, expanding on the config snippet provided at #9743

What are those updates you refer to? If it's something small, I'd say we could upgrade the snippet itself. However, if it's long enough, it could replace the dedicated page we have for Poetry.

[juantocamidokura]

Hi @humitos . Sorry for the late response, I was on PTO.

Taking into account your comment, I think that just removing the page is the most sensible solution. I'll open a PR to fix it :D

Thanks for your feedback