docs: add example documenting pip install --target

[neevets]

Adds a usage example for the --target flag to improve discoverability.

Fixes #12667

[neevets]

This PR only updates documentation and does not require a changelog entry.

[pfmoore]

IMO, this is a bad example. It suggests that --target is suited for installing packages into an existing Python installation, and that isn't the case. The intended use for --target is in embedding scenarios, where you create a brand new, empty directory, and use pip install --target to install requirements into that directory. Your embedded application can then add the directory to the Python interpreter's path.

Using --target to install into an existing site-packages directory may work, but it's very much a "use at your own risk" scenario, and not one that we want to encourage.

[neevets]

Thanks for the clarification. I've updated the example to use an initially empty
directory and clarified that the intended use case is embedding scenarios.

[pfmoore]

Thanks, that's a lot better.

I'm still not sure we even want to make the --target option "more discoverable", to be honest. So I'll leave it up to the other maintainers to comment, and decide whether to merge this.

[henryiii]

What I've used --target for is creating zipapp's: https://github.com/scikit-hep/particle/blob/8ffe2da9151aedf8f15d49a07ccf3401b7815aef/noxfile.py#L55-L91 creates particle.pyz.

Basically you create a dir, install pure Python dependencies with --target, then zip it with python -m zippapp.

[notatallshaw]

What about keeping the description simple and adding a warning? E.g.

    Install packages into the specified directory instead of the default
    site-packages location.


    .. warning::
    
       The ``--target`` option is intended for specialized scenarios, such as
       embedding Python where a new, empty directory is explicitly added to
       ``sys.path``. Using it for general installation can lead to unexpected
       behavior (for example with namespace packages or upgrades), since
       ``pip`` is designed to install packages into standard environments.

Many users are using --target, so documenting it makes sense, but I think it's a good opportunity to also highlight it can easily lead to unexpected behavior.

[neevets]

Thanks for the suggestion. I’ve updated the section to keep the description simple and added a warning highlighting the intended use of --target and the potential for unexpected behavior when used outside embedding scenarios.

[notatallshaw]

I mean, I'm +1 on this approach as I suggested it, but I'm sure other maintainers will have thoughts about the specific wording.