Merge pull request #519 from kuba/docs

Docs improvements

README.rst

@@ -1,3 +1,13 @@
+.. notice for github users
+
+Official **documentation**, including `installation instructions`_, is
+available at https://letsencrypt.readthedocs.org.
+
+Generic information about Let's Encrypt project can be found at
+https://letsencrypt.org. Please read `Frequently Asked Questions (FAQ)
+<https://letsencrypt.org/faq/>`_.
+
+
 About the Let's Encrypt Client
 ==============================
 
@@ -47,6 +57,9 @@ server automatically!::
    :target: https://quay.io/repository/letsencrypt/lets-encrypt-preview
    :alt: Docker Repository on Quay.io
 
+.. _`installation instructions`:
+   https://letsencrypt.readthedocs.org/en/latest/using.html
+
 .. _watch demo video: https://www.youtube.com/watch?v=Gas_sSB-5SU
 
 
@@ -85,7 +98,7 @@ Current Features
 Links
 -----
 
-Documentation: https://letsencrypt.readthedocs.org/
+Documentation: https://letsencrypt.readthedocs.org
 
 Software project: https://github.com/letsencrypt/lets-encrypt-preview
 

docs/contributing.rst

@@ -17,6 +17,14 @@ Now you can install the development packages:
 
    ./venv/bin/pip install -r requirements.txt -e .[dev,docs,testing]
 
+.. note:: `-e` (short for `--editable`) turns on *editable mode* in
+          which any source code changes in the current working
+          directory are "live" and no further `pip install ...`
+          invocations are necessary while developing.
+
+          This is roughly equivalent to `python setup.py develop`. For
+          more info see `man pip`.
+
 The code base, including your pull requests, **must** have 100% test
 statement coverage **and** be compliant with the :ref:`coding style
 <coding-style>`.

docs/pkgs/acme/index.rst

@@ -51,9 +51,6 @@ Errors
    :members:
 
 
-   :members:
-
-
 Utilities
 ---------
 

docs/using.rst

@@ -5,9 +5,9 @@ Using the Let's Encrypt client
 Quick start
 ===========
 
-Using docker you can quickly get yourself a testing cert. From the
+Using Docker_ you can quickly get yourself a testing cert. From the
 server that the domain your requesting a cert for resolves to,
-download docker, and issue the following command
+`install Docker`_, issue the following command:
 
 .. code-block:: shell
 
@@ -16,9 +16,31 @@ download docker, and issue the following command
                -v "/var/lib/letsencrypt:/var/lib/letsencrypt" \
                quay.io/letsencrypt/lets-encrypt-preview:latest
 
-And follow the instructions. Your new cert will be available in
+and follow the instructions. Your new cert will be available in
 ``/etc/letsencrypt/certs``.
 
+.. _Docker: https://docker.com
+.. _`install Docker`: https://docs.docker.com/docker/userguide/
+
+
+Getting the code
+================
+
+Please `install Git`_ and run the following commands:
+
+.. code-block:: shell
+
+   git clone https://github.com/letsencrypt/lets-encrypt-preview
+   cd lets-encrypt-preview
+
+Alternatively you could `download the ZIP archive`_ and extract the
+snapshot of our repository, but it's strongly 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/lets-encrypt-preview/archive/master.zip
+
 
 Prerequisites
 =============
@@ -31,13 +53,6 @@ In general:
 
 * ``sudo`` is required as a suggested way of running privileged process
 * `SWIG`_ is required for compiling `M2Crypto`_
-
-  .. _new-swig:
-  .. note:: If your operating system uses SWIG 3.0.5+, you will need
-            to run ``pip install -r requirements-swig-3.0.5.txt -r
-            requirements.txt .`` instead of the standard ``pip
-            install -r requirements.txt .``.
-
 * `Augeas`_ is required for the Python bindings
 
 
@@ -79,8 +94,6 @@ Fedora
 
    sudo ./bootstrap/fedora.sh
 
-.. note:: Fedora 22 uses SWIG 3.0.5+, use the :ref:`modified pip
-          command for installation <new-swig>`.
 
 Centos 7
 --------
@@ -106,11 +119,32 @@ Installation
    virtualenv --no-site-packages -p python2 venv
    ./venv/bin/pip install -r requirements.txt .
 
+.. warning:: Please do **not** use ``python setup.py install``. Please
+             do **not** attempt the installation commands as
+             superuser/root and/or without Virtualenv_, e.g. ``sudo
+             python setup.py install``, ``sudo pip install``, ``sudo
+             ./venv/bin/...``. These modes of operation might corrupt
+             your operating system and are **not supported** by the
+             Let's Encrypt team!
+
+.. note:: If your operating system uses SWIG 3.0.5+, you will need to
+          run ``pip install -r requirements-swig-3.0.5.txt -r
+          requirements.txt .`` instead. Known affected systems:
+
+          * Fedora 22
+          * some versions of Mac OS X
+
 
 Usage
 =====
 
-The letsencrypt commandline tool has a builtin help:
+To get a new certificate run:
+
+.. code-block:: shell
+
+   ./venv/bin/letsencrypt auth
+
+The ``letsencrypt`` commandline tool has a builtin help:
 
 .. code-block:: shell
 
@@ -120,3 +154,4 @@ The letsencrypt commandline tool has a builtin help:
 .. _Augeas: http://augeas.net/
 .. _M2Crypto: https://github.com/M2Crypto/M2Crypto
 .. _SWIG: http://www.swig.org/
+.. _Virtualenv: https://virtualenv.pypa.io

letsencrypt/network2.py

@@ -25,7 +25,7 @@ class Network(object):
 
     .. todo::
        Clean up raised error types hierarchy, document, and handle (wrap)
-       instances of `.DeserializationError` raised in `from_json()``.
+       instances of `.DeserializationError` raised in `from_json()`.
 
     :ivar str new_reg_uri: Location of new-reg
     :ivar key: `.JWK` (private)
@@ -257,13 +257,12 @@ class Network(object):
 
         # TODO: Boulder does not set Location or Link on update
         # (c.f. acme-spec #94)
-
         updated_regr = self._regr_from_response(
             response, uri=regr.uri, new_authzr_uri=regr.new_authzr_uri,
             terms_of_service=regr.terms_of_service)
         if updated_regr != regr:
-            # TODO: Boulder reregisters with new recoveryToken and new URI
             raise errors.UnexpectedUpdate(regr)
+
         return updated_regr
 
     def agree_to_tos(self, regr):