Improve documentation (#833)

* Move and duplicate note about running under multiple Python versions to the start of each command's section.
* Add note about using `--upgrade` and `--upgrade-package` together following #831.
* Document `--output-file`.

README.rst

@@ -50,6 +50,13 @@ project's virtual environment.
 Example usage for ``pip-compile``
 =================================
 
+The ``pip-compile`` command lets you compile a ``requirements.txt`` file from
+your dependencies, specified in either ``setup.py`` or ``requirements.in``.
+
+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.
+
 Requirements from ``setup.py``
 ------------------------------
 
@@ -163,9 +170,26 @@ To update a specific package to the latest or a specific version use the
     $ pip-compile --upgrade-package flask --upgrade-package requests  # update both the flask and requests packages
     $ pip-compile -P flask -P requests==2.0.0  # update the flask package to the latest, and requests to v2.0.0
 
-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.
+You can combine ``--upgrade`` and ``--upgrade-package`` in one command, to
+provide constraints on the allowed upgrades. For example to upgrade all
+packages whilst constraining requests to the latest version less than 3.0:
+
+.. code-block:: bash
+
+    $ pip-compile --upgrade --upgrade-package 'requests<3.0'
+
+Output File
+-----------
+
+To output the pinned requirements in a filename other than
+``requirements.txt``, use ``--output-file``. This might be useful for compiling
+multiple files, for example with different constraints on flask to test a
+library with both versions using `tox <https://tox.readthedocs.io/en/latest/>`__:
+
+.. code-block:: bash
+
+    $ pip-compile --upgrade-package 'flask<1.0' --output-file requirements-flask0x.txt
+    $ pip-compile --upgrade-package 'flask<2.0' --output-file requirements-flask1x.txt
 
 Configuration
 -------------
@@ -198,6 +222,10 @@ your virtual environment to reflect exactly what's in there. This will
 install/upgrade/uninstall everything necessary to match the
 ``requirements.txt`` contents.
 
+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.
+
 **Be careful**: ``pip-sync`` is meant to be used only with a
 ``requirements.txt`` generated by ``pip-compile``.