Merge pull request #1023 from tekumara/improve-install-docs

pip-tools should be installed in the project's virtual environment

README.rst

@@ -34,8 +34,8 @@ even when you've pinned them.  `You do pin them, right?`_
 Installation
 ============
 
-As part of a Python project's environment tooling (similar to ``pip``), it's
-recommended to install ``pip-tools`` in each project's `virtual environment`_:
+Similar to ``pip``, ``pip-tools`` must be installed in each of your project's
+`virtual environments`_:
 
 .. code-block:: bash
 
@@ -45,7 +45,7 @@ recommended to install ``pip-tools`` in each project's `virtual environment`_:
 **Note**: all of the remaining example commands assume you've activated your
 project's virtual environment.
 
-.. _virtual environment: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments
+.. _virtual environments: https://packaging.python.org/tutorials/installing-packages/#creating-virtual-environments
 
 Example usage for ``pip-compile``
 =================================
@@ -57,6 +57,11 @@ Run it with ``pip-compile`` or  ``python -m piptools compile``. If you use
 multiple Python versions, you can run ``pip-compile`` as ``py -X.Y -m piptools
 compile`` on Windows and ``pythonX.Y -m piptools compile`` on other systems.
 
+``pip-compile`` should be run from the same virtual environment as your
+project so conditional dependencies that require a specific Python version,
+or other environment markers, resolve relative to your project's
+environment.
+
 **Note**: ensure you don't have ``requirements.txt`` if you compile
 ``setup.py`` or ``requirements.in`` from scratch, otherwise, it might
 interfere.
@@ -303,6 +308,10 @@ Run it with ``pip-sync`` or ``python -m piptools sync``. If you use multiple
 Python versions, you can also run ``py -X.Y -m piptools sync`` on Windows and
 ``pythonX.Y -m piptools sync`` on other systems.
 
+``pip-sync`` must be installed into and run from the same virtual
+environment as your project to identify which packages to install
+or upgrade.
+
 **Be careful**: ``pip-sync`` is meant to be used only with a
 ``requirements.txt`` generated by ``pip-compile``.