Added command reference documentation

Fixes #109.

8 files changed, 309 insertions, 4 deletions

diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 21fdbeb..57a9d4f 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -4,12 +4,11 @@ Reference Guide
 .. toctree::
    :maxdepth: 2
 
-   wheel
    wheel_keygen
    wheel_sign
-   wheel_unsign
    wheel_verify
-   wheel_unpack
+   wheel_unsign
+   wheel_convert
    wheel_install
+   wheel_unpack
    wheel_install_scripts
-   wheel_convert
diff --git a/docs/reference/wheel_convert.rst b/docs/reference/wheel_convert.rst
new file mode 100644
index 0000000..bff25b2
--- /dev/null
+++ b/docs/reference/wheel_convert.rst
@@ -0,0 +1,47 @@
+wheel convert
+=============
+
+Usage
+-----
+
+::
+
+    wheel convert [options] <egg_file_or_directory> [egg_file_or_directory...]
+
+
+Description
+-----------
+
+Convert one or more eggs (``.egg``; made with ``bdist_egg``) or Windows
+installers (``.exe``; made with ``bdist_wininst``) into wheels.
+
+Egg names must match the standard format:
+
+* ``<project>-<version>-pyX.Y`` for pure Python wheels
+* ``<project>-<version>-pyX.Y-<arch>`` for binary wheels
+
+
+Options
+-------
+
+.. option:: -d, --dest-dir <dir>
+
+    Directory to store the generated wheels in (defaults to current directory).
+
+
+Examples
+--------
+
+* Convert a single egg file::
+
+    $ wheel convert foobar-1.2.3-py2.7.egg
+    $ ls *.whl
+    foobar-1.2.3-py27-none.whl
+
+* If the egg file name is invalid::
+
+    $ wheel convert pycharm-debug.egg
+    "pycharm-debug.egg" is not a valid egg name (must match at least name-version-pyX.Y.egg)
+    $ echo $?
+    1
+
diff --git a/docs/reference/wheel_install.rst b/docs/reference/wheel_install.rst
new file mode 100644
index 0000000..d056078
--- /dev/null
+++ b/docs/reference/wheel_install.rst
@@ -0,0 +1,63 @@
+wheel install
+=============
+
+Usage
+-----
+
+::
+
+    wheel install <wheel_file>
+
+
+Description
+-----------
+
+Install the given wheel file to ``site-packages``.
+
+This unpacks the wheel file to the site packages directory and installs
+wrappers for any console scripts defined in the wheel metadata.
+
+It also checks that the hashes and file sizes match with those in ``RECORD``
+and exits with an error if it encounters a mismatch.
+
+
+Options
+-------
+
+.. option:: --force
+
+    Install the wheel even if its tags indicate it is incompatible with the
+    current CPU architecture, Python version or Python implementation.
+
+.. options:: -d, --wheel-dir <wheel_dir>
+
+    Specify a directory containing wheels. This will be used for dependency
+    lookup.
+
+.. option:: -r, --requirements-file <requirements_file>
+
+    Specify a file containing requirements to install. The wheels listed here
+    will be installed in addition to the wheel given as the argument.
+
+.. option:: -l, --list
+
+    List wheels which would be installed, but don't actually install anything.
+
+Examples
+--------
+
+* Unpack a wheel::
+
+    $ wheel install someproject-1.5.0-py2-py3-none.whl
+    Unpacking to: ./someproject-1.5.0
+
+* If a file's hash does not match::
+
+    $ wheel install someproject-1.5.0-py2-py3-none.whl
+    Unpacking to: ./someproject-1.5.0
+    Traceback (most recent call last):
+    ...
+    wheel.install.BadWheelFile: Bad hash for file 'mypackage/module.py'
+    $ echo $?
+    1
+
diff --git a/docs/reference/wheel_install_scripts.rst b/docs/reference/wheel_install_scripts.rst
new file mode 100644
index 0000000..a55919f
--- /dev/null
+++ b/docs/reference/wheel_install_scripts.rst
@@ -0,0 +1,33 @@
+wheel install-scripts
+=====================
+
+Usage
+-----
+
+::
+
+    wheel install-scripts <distribution>
+
+
+Description
+-----------
+
+Install wrappers for the ``console_scripts`` entry points for given
+distribution.
+
+This (re)generates any wrappers (``.exe`` on Windows) for any
+``console_scripts`` entry points and installs them in the current scripts
+directory.
+
+Options
+-------
+
+This command has no options.
+
+
+Examples
+--------
+
+::
+
+    $ wheel install-scripts someproject
diff --git a/docs/reference/wheel_keygen.rst b/docs/reference/wheel_keygen.rst
new file mode 100644
index 0000000..73806c2
--- /dev/null
+++ b/docs/reference/wheel_keygen.rst
@@ -0,0 +1,37 @@
+wheel keygen
+============
+
+Usage
+-----
+
+::
+
+    wheel keygen
+
+
+Description
+-----------
+
+Generates an ED25519 keypair for the purpose of signing wheels.
+
+Repeated invocations of this command will each add a new key to the keyring.
+The latest key will always be used for signing wheels.
+
+Options
+-------
+
+This command has no options.
+
+
+Examples
+--------
+
+::
+
+    $ wheel keygen
+    Created Ed25519 keypair with vk=ArGKRsTbmnMcO5aW2Of4xkictMrmUyxutJStwzlZcDk
+    in <PlaintextKeyring with no encyption v.1.0 at /home/alex/.local/share/python_keyring/keyring_pass.cfg>
+    Trusting ArGKRsTbmnMcO5aW2Of4xkictMrmUyxutJStwzlZcDk to sign and verify all packages.
+
+.. note:: The above key is not actually used to sign any wheels, so do not
+    trust it!
diff --git a/docs/reference/wheel_unpack.rst b/docs/reference/wheel_unpack.rst
new file mode 100644
index 0000000..420f610
--- /dev/null
+++ b/docs/reference/wheel_unpack.rst
@@ -0,0 +1,47 @@
+wheel unpack
+============
+
+Usage
+-----
+
+::
+
+    wheel unpack <wheel_file>
+
+
+Description
+-----------
+
+Unpack the given wheel file.
+
+This is the equivalent of ``unzip <wheel_file>``, except that it also checks
+that the hashes and file sizes match with those in ``RECORD`` and exits with an
+error if it encounters a mismatch.
+
+
+Options
+-------
+
+.. option:: -d, --dest-dir <dir>
+
+    Directory to unpack the wheel into.
+
+
+Examples
+--------
+
+* Unpack a wheel::
+
+    $ wheel unpack someproject-1.5.0-py2-py3-none.whl
+    Unpacking to: ./someproject-1.5.0
+
+* If a file's hash does not match::
+
+    $ wheel unpack someproject-1.5.0-py2-py3-none.whl
+    Unpacking to: ./someproject-1.5.0
+    Traceback (most recent call last):
+    ...
+    wheel.install.BadWheelFile: Bad hash for file 'mypackage/module.py'
+    $ echo $?
+    1
+
diff --git a/docs/reference/wheel_unsign.rst b/docs/reference/wheel_unsign.rst
new file mode 100644
index 0000000..419d467
--- /dev/null
+++ b/docs/reference/wheel_unsign.rst
@@ -0,0 +1,39 @@
+wheel unsign
+============
+
+Usage
+-----
+
+::
+
+    wheel unsign <wheel_file>
+
+
+Description
+-----------
+
+Remove the digital signature from the given wheel file.
+
+This removes the ``RECORD.jws`` file from the end of the archive.
+
+
+Options
+-------
+
+This command has no options.
+
+
+Examples
+--------
+
+* Unsign a wheel::
+
+    $ wheel unsign someproject-X.Y.Z-py2-py3-none.whl
+
+* If the wheel isn't signed::
+
+    $ wheel unsign someproject-X.Y.Z-py2-py3-none.whl
+    The wheel is not signed (RECORD.jws not found at end of the archive).
+    $ echo $?
+    1
+
diff --git a/docs/reference/wheel_verify.rst b/docs/reference/wheel_verify.rst
new file mode 100644
index 0000000..2a81f12
--- /dev/null
+++ b/docs/reference/wheel_verify.rst
@@ -0,0 +1,40 @@
+wheel verify
+============
+
+Usage
+-----
+
+::
+
+    wheel verify <wheel_file>
+
+
+Description
+-----------
+
+Verify that the wheel's signature is internally consistent.
+
+This does not verify the files in the archive contents. For that, you must use
+the ``wheel unpack`` or ``wheel install`` commands.
+
+
+Options
+-------
+
+This command has no options.
+
+
+Examples
+--------
+
+* Verify a wheel::
+
+    $ wheel verify someproject-X.Y.Z-py2-py3-none.whl
+
+* If the wheel is not signed::
+
+    $ wheel verify someproject-X.Y.Z-py2-py3-none.whl
+    The wheel is not signed (RECORD.jws not found at end of the archive).
+    $ echo $?
+    1
+