The pip documentation lacks too much wordings (to my eyes), about parameters to deal with source and destinations.
I've experienced strange things installing Sphinx with pip3 and playing with the options available to seemingly allow me to install it precisely where I wanted (for some reasons, I want to have each thing in its own directory). I say “playing”, not that I did not read the doc nor tried --help, but because the pip3 help install did not help, and the pip install official documentation page is too short on this and actually says not more than the pip3 help install.
Here are the experiments done and the observations.
First case with --root
I downloaded the current Sphinx repository tarball, unpacked it, get into the newly created directory and did:
pip3 install --root /home/<user-name>/apps/sphinx -e .
I though this would be the same as --prefix, as there was no --prefix option visibly available. To my surprise, it installed the commands in the bin directory of Python3 (which is also installed locally in its own directory) along to some things in its library directory, and strange, instead of a /home/<user-name>/apps/sphinx directory, I get a /home/<user-name>/apps/sphinx/home/<user-name>/apps/sphinx/…: it appended the specified path to itself.
How especially the last point does make sense? What's the purpose of --root?
Second case with --target
Then I though if it's not --root, that may be --target, so I did (after a clean up):
pip3 install --target /home/<user-name>/apps/sphinx -e .
It did not work, complaining about an unrecognized --home option.
What is this --home (which I did not specified) it complains about, and what exactly is --target?
Third case with --install-option='--prefix=…'
After some web‑searching and a thread on StackOverflow, I tried this:
pip3 install --install-option='--prefix=/home/<user-name>/apps/sphinx' -e .
It just complained it could not install a .pth file and something is wrong with my PYTHONPATH, which was addressable restarting the same with the addition of a variable definition:
export PYTHONPATH=/home/<user-name>/apps/sphinx/lib/python3.4/site-packages
pip3 install --install-option='--prefix=/home/<user-name>/apps/sphinx' -e .
I just had to the set PYTHONPATH even before the directory actually exists and anything was installed in it, but this one was OK (whether or not pip should update PYTHONPATH itself during the process and remind to set it up definitively, is a debatable question).
This option, which was the good one, was also the less clearly visible one.
Another last related one:
What's the difference between --editable and --src?
Update #1
I can't tell if it's Sphinx related, but I noticed two additional things.
Doing
pip3 install --install-option='--prefix=<install-dir>' -e <repository-dir>
where repository-dir is a local check out of Sphinx, Sphinx gets installed in install-dir, is listed by pip3 list but can't be uninstalled.
On the opposite, doing
pip3 install --install-option='--prefix=<install-dir>' Sphinx
that is, letting pip3 retrieving an archive, Sphinx is not installed in install-dir, is installed in the python directory instead, is listed by pip3 list and can be uninstalled.
Depending on whether the source is a local repository or a remote archive, it won't be installed at the same location and will not be or will be uninstallable.
Dependencies were not affected, were handled the same way in both cases (installed where expected, listed, and uninstallable).
Update #2
The behaviour with --root make me feel about a kind of fake‑root (like the one you get when building a Debian package or when cross‑compiling). If it's intended to be the same, then the path which surprised me, is on the contrary, expected.