Docs issue: `setup_requires` is explained as problematic in cookbook, but no comparable replacement appears to be given

https://pip.readthedocs.io/en/1.4.1/cookbook.html#controlling-setup-requires

This section and various other sources (like https://github.com/cython/cython/issues/2730#issuecomment-473716573 and other helpful comments) say that setup_requires has issues due to its reliance on easy_install and should be avoided.

However, the above cookbook section doesn’t actually appear to offer any alternative! I think if you want people to stop using it, this section should really show one. All it appears to do is to show how to work around the package index options not working while still using setup_requires, or am I misunderstanding this section completely?

It would be incredibly helpful if that cookbook section could be expanded to add a demonstration of a full example of a modern setup_requires-equivalent, how it should be done if one wants to avoid deprecated functionality. (or if that is already somewhere else in the cookbook, maybe it would be wise to add a link/reference here?) Because it’s not obvious at all to me how to do it 😕

PS: you’re doing great work this is just a minor bump I found worth reporting!

[pradyunsg]

Documentation PRs to clarify would be welcome.

[uranusjr]

@JonasT setupmeta is a tool that auto-generates some setup.py content (I know it’s not entirely accurate, but let’s keep things simple). It is not essential to packaging, thus not mentioned in docs.