Merge pull request #852 from theupdateframework/better_installation_i…

…nstructions

Clarify installation procedures

docs/CONTRIBUTORS.rst

@@ -81,38 +81,29 @@ and instructions for installing locally from source are provided here:
     $ cd virtualenv-15.0.3
     $ python virtualenv.py myVE
 
-External Dependencies
-=====================
-
-Before installing TUF, a couple of its Python dependencies have non-Python dependencies
-of their own that should installed first.  PyCrypto and PyNaCl (third-party dependencies
-needed by the repository tools) require Python and FFI (Foreign Function Interface)
-development header files. Debian-based distributions can install these header
-libraries with apt (Advanced Package Tool.)
-::
 
-    $ apt-get install build-essential libssl-dev libffi-dev python-dev
+Development Installation
+========================
 
-Fedora-based distributions can install these libraries with dnf.
-::
+To work on the TUF project, it's best to perform a development install.
 
-    $ dnf install libffi-devel redhat-rpm-config openssl-devel
+1. First, `install non-Python dependencies <INSTALLATION.rst#non-python-dependencies>`_.
 
-OS X users can install these header libraries with the `Homebrew <https://brew.sh/>`_ package manager.
-::
+2. Then clone this repository:
 
-    $ brew install python
-    $ brew install libffi
+::
 
-Development Installation
-========================
+    $ git clone https://github.com/theupdateframework/tuf
 
-Installation of minimal, optional, development, and testing requirements
-can then be accomplished with one command:
+3. Then perform a full, editable/development install.  This will include all
+   optional cryptographic support, the testing/linting dependencies, etc.
+   With a development installation, modifications to the code in the current
+   directory will affect the installed version of TUF.
 ::
 
     $ pip install -r dev-requirements.txt
 
+
 Testing
 =======
 

docs/INSTALLATION.rst

@@ -1,8 +1,9 @@
 Installation
-------------
+============
 
-*pip* is the recommended installer.  The project can be installed either
-locally or from the Python Package Index.  All `TUF releases
+*pip* is the recommended installer for installing and managing Python packages.
+The project can be installed either locally or from the Python Package Index.
+All `TUF releases
 <https://github.com/theupdateframework/tuf/releases>`_ are cryptographically
 signed, with GPG signatures available on both GitHub and `PyPI
 <https://pypi.python.org/pypi/tuf/>`_.  PGP key information for our maintainers
@@ -15,8 +16,13 @@ The latest release and its packaging information, such as who signed the
 release and their PGP fingerprint, can also be found on our 1-year `roadmap
 <ROADMAP.md>`_.
 
-Assuming you trust the maintainer's PGP key, the detached ASC signature
-can be downloaded and verified.  For example:
+
+
+Release Verification
+--------------------
+
+Assuming you trust `the maintainer's PGP key <MAINTAINERS.txt>`_), the detached
+ASC signature can be downloaded and verified.  For example:
 
 ::
 
@@ -26,25 +32,69 @@ can be downloaded and verified.  For example:
    gpg:                using RSA key 3E87BB339378BC7B3DD0E5B25DEE9B97B0E2289A
    gpg: Good signature from "Vladimir Diaz (Vlad) <[email protected]>" [ultimate]
 
-Installation instructions:
 
-::
 
-    pip - installing and managing Python packages (recommended)
+Simple Installation
+-------------------
 
-    Installing from Python Package Index (https://pypi.python.org/pypi).
-    Note: Please use "pip install --no-use-wheel tuf" if your version
-    of pip <= 1.5.6
+If you are only using ed25519-based cryptography, you can employ a pure-Python
+installation, done simply with one of the following commands:
+
+Installing from Python Package Index (https://pypi.python.org/pypi).
+(Note: Please use "pip install --no-use-wheel tuf" if your version
+of pip <= 1.5.6)
+::
     $ pip install tuf
 
-    Installing from local source archive.
+
+**Alternatively**, if you wish to install from a GitHub release you've already
+downloaded, or a package you obtained in another way, you can instead:
+
+Install from a local source archive:
+::
     $ pip install <path to archive>
 
-    Or from the root directory of the unpacked archive.
+Or install from the root directory of the unpacked archive:
+::
     $ pip install .
 
-    By default, C extensions are not installed and only Ed25519 signatures can
-    be verified in pure Python.  To fully support RSA, Ed25519, ECDSA, and
-    other crypto, you must install the extra dependencies declared by
-    securesystemslib:
-    $ pip install securesystemslib[crypto,pynacl]
+
+
+Install with More Cryptographic Flexibility
+-------------------------------------------
+
+By default, C extensions are not installed and only Ed25519 signatures can
+be verified, in pure Python.  To fully support RSA, Ed25519, ECDSA, and
+other crypto, you must install the extra dependencies declared by
+securesystemslib.  **Note**: that may require non-Python dependencies, so if
+you encounter an error attempting this pip command, see
+`more instructions below <#non-python-dependencies>`_).
+::
+    $ pip install securesystemslib[crypto,pynacl] tuf
+
+
+
+Non-Python Dependencies
+-----------------------
+
+If you encounter errors during installation, you may be missing
+certain system libraries.
+
+For example, PyNaCl and Cryptography -- two libraries used in the full
+installation to support certain cryptographic functions -- may require FFI
+(Foreign Function Interface) development header files.
+
+Debian-based distributions can install the necessary header libraries with apt
+(Advanced Package Tool.)
+::
+    $ apt-get install build-essential libssl-dev libffi-dev python-dev
+
+Fedora-based distributions can instead install these libraries with dnf.
+::
+    $ dnf install libffi-devel redhat-rpm-config openssl-devel
+
+OS X users can install these header libraries with the `Homebrew <https://brew.sh/>`_
+package manager, among other options.
+::
+    $ brew install python
+    $ brew install libffi