Reorg User Guide

docs/using.rst

@@ -2,44 +2,95 @@
 Using the Let's Encrypt client
 ==============================
 
+Welcome to the User Guide!
 
-Getting the code
+.. contents:: Table of Contents
-================
+   :local:
 
-Please `install Git`_ and run the following commands:
+
+Installation
+============
+
+Unless you have a very specific requirements, we kindly ask you to use
+the letsencrypt-auto_ method described below. It's the fastest, the
+most thourougly tested and the most reliable way of getting our
+software and the free SSL certificates!
+
+.. letsencrypt-auto:
+
+letsencrypt-auto
+----------------
+
+``letsencrypt-auto`` is a wrapper which installs some dependencies
+from your OS standard package repostories (e.g using `apt-get` or
+`yum`), and for other depencies it sets up a virtualized Python
+environment with packages downloaded from PyPI [#venv]_. It also
+provides automated updates.
+
+Firstly, please `install Git`_ and run the following commands:
 
 .. code-block:: shell
 
    git clone https://github.com/letsencrypt/letsencrypt
    cd letsencrypt
 
-Alternatively you could `download the ZIP archive`_ and extract the
+.. warning:: Alternatively you could `download the ZIP archive`_ and
-snapshot of our repository, but it's strongly recommended to use the
+   extract the snapshot of our repository, but it's strongly
-above method instead.
+   recommended to use the above method instead.
 
 .. _`install Git`: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
 .. _`download the ZIP archive`:
    https://github.com/letsencrypt/letsencrypt/archive/master.zip
 
-
-Installation and Usage
-======================
-
 To install and run the client you just need to type:
 
 .. code-block:: shell
 
    ./letsencrypt-auto
 
-(Once letsencrypt is packaged by distributions, the command will just be
+Throughout the documentation, whenever you see references to
-``letsencrypt``.  ``letsencrypt-auto`` is a wrapper which installs virtualized
+``letsencrypt`` script/binary, you can subsitute in
-dependencies and provides automated updates during the beta program)
+``letsencrypt-auto``. For example, to get the help you would type:
-
-The ``letsencrypt`` commandline tool has a builtin help:
 
 .. code-block:: shell
 
-   ./letsencrypt-auto --help
+  ./letsencrypt-auto --help
+
+
+Running with Docker
+-------------------
+
+Docker_ is another way to quickly obtain testing certs. From the
+server that the domain your requesting a cert for resolves to,
+`install Docker`_, issue the following command:
+
+.. code-block:: shell
+
+   sudo docker run -it --rm -p 443:443 --name letsencrypt \
+               -v "/etc/letsencrypt:/etc/letsencrypt" \
+               -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
+               quay.io/letsencrypt/letsencrypt:latest auth
+
+and follow the instructions. Your new cert will be available in
+``/etc/letsencrypt/certs``.
+
+.. _Docker: https://docker.com
+.. _`install Docker`: https://docs.docker.com/userguide/
+
+
+Distro packages
+---------------
+
+Unfortunately, this is an ongoing effort. If you'd like to package
+Let's Encrypt client for your distribution of choice please have a
+look at :doc:`packaging`.
+
+
+From source
+-----------
+
+Installation from source is only supported for developers and the
+whole process is described in :doc:`contributing`.
 
 .. warning:: Please do **not** use ``python setup.py install`` or
    ``python pip install .``. Please do **not** attempt the
@@ -51,7 +102,7 @@ The ``letsencrypt`` commandline tool has a builtin help:
 
 
 Configuration file
-------------------
+==================
 
 It is possible to specify configuration file with
 ``letsencrypt-auto --config cli.ini`` (or shorter ``-c cli.ini``). An
@@ -70,22 +121,8 @@ By default, the following locations are searched:
 .. keep it up to date with constants.py
 
 
-Running with Docker
+.. rubric:: Footnotes
-===================
 
-Docker_ is another way to quickly obtain testing certs. From the
+.. [#venv] By using this virtualized Python enviroment (`virtualenv
-server that the domain your requesting a cert for resolves to,
+           <https://virtualenv.pypa.io>`_) we don't pollute the main
-`install Docker`_, issue the following command:
+           OS space with packages from PyPI!
-
-.. code-block:: shell
-
-   sudo docker run -it --rm -p 443:443 --name letsencrypt \
-               -v "/etc/letsencrypt:/etc/letsencrypt" \
-               -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
-               quay.io/letsencrypt/letsencrypt:latest auth
-
-and follow the instructions. Your new cert will be available in
-``/etc/letsencrypt/certs``.
-
-.. _Docker: https://docker.com
-.. _`install Docker`: https://docs.docker.com/userguide/