Merge pull request #525 from skeuomorf/installation-docs

Added canonical installation document with details about various platforms

3 files changed, 78 insertions, 65 deletions

diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 926ec7d1..12d2d9f6 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -13,52 +13,4 @@ The `OpenSSL`_ C library.
 
         The string name of this backend: ``"openssl"``
 
-Using your own OpenSSL on Linux
--------------------------------
-
-Python links to OpenSSL for its own purposes and this can sometimes cause
-problems when you wish to use a different version of OpenSSL with cryptography.
-If you want to use cryptography with your own build of OpenSSL you will need to
-make sure that the build is configured correctly so that your version of
-OpenSSL doesn't conflict with Python's.
-
-The options you need to add allow the linker to identify every symbol correctly
-even when multiple versions of the library are linked into the same program. If
-you are using your distribution's source packages these will probably be
-patched in for you already, otherwise you'll need to use options something like
-this when configuring OpenSSL:
-
-.. code-block:: console
-
-    $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
-
-You'll also need to generate your own ``openssl.ld`` file. For example::
-
-    OPENSSL_1.0.1F_CUSTOM {
-        global:
-            *;
-    };
-
-You should replace the version string on the first line as appropriate for your
-build.
-
-Using your own OpenSSL on OS X
-------------------------------
-
-To link cryptography against a custom version of OpenSSL you'll need to set
-``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via
-`Homebrew`_:
-
-.. code-block:: console
-
-    $ brew install openssl
-
-Then install cryptography linking against the brewed version:
-
-.. code-block:: console
-
-    $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
-
-
 .. _`OpenSSL`: https://www.openssl.org/
-.. _`Homebrew`: http://brew.sh
diff --git a/docs/index.rst b/docs/index.rst
index b800bcaf..93b25ecf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,29 +5,15 @@ Welcome to ``cryptography``
 primitives. We hope it'll be your one-stop-shop for all your cryptographic
 needs in Python.
 
-Installing
-----------
-
+Installation
+------------
 You can install ``cryptography`` with ``pip``:
 
 .. code-block:: console
 
     $ pip install cryptography
 
-.. note::
-
-    If you're on Windows you'll need to make sure you have OpenSSL installed.
-    There are `pre-compiled binaries`_ available. If your installation is in
-    an unusual location set the ``LIB`` and ``INCLUDE`` environment variables
-    to include the corresponding locations. For example:
-    
-    .. code-block:: console
-    
-        C:\> \path\to\vcvarsall.bat x86_amd64
-        C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB%
-        C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
-        C:\> pip install cryptography
-
+see :doc:`Installation<installation>`  for more information
 
 Why a new crypto library for Python?
 ------------------------------------
@@ -90,6 +76,7 @@ The ``cryptography`` open source project
 .. toctree::
     :maxdepth: 2
 
+    installation
     contributing
     security
     api-stability
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 00000000..2206107e
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,74 @@
+Installing
+==========
+
+You can install ``cryptography`` with ``pip``:
+
+.. code-block:: console
+
+    $ pip install cryptography
+
+Installation Notes
+==================
+On Windows
+----------
+If you're on Windows you'll need to make sure you have OpenSSL installed.
+There are `pre-compiled binaries`_ available. If your installation is in
+an unusual location set the ``LIB`` and ``INCLUDE`` environment variables
+to include the corresponding locations. For example:
+
+.. code-block:: console
+
+    C:\> \path\to\vcvarsall.bat x86_amd64
+    C:\> set LIB=C:\OpenSSL-1.0.1f-64bit\lib;%LIB%
+    C:\> set INCLUDE=C:\OpenSSL-1.0.1f-64bit\include;%INCLUDE%
+    C:\> pip install cryptography
+
+Using your own OpenSSL on Linux
+-------------------------------
+
+Python links to OpenSSL for its own purposes and this can sometimes cause
+problems when you wish to use a different version of OpenSSL with cryptography.
+If you want to use cryptography with your own build of OpenSSL you will need to
+make sure that the build is configured correctly so that your version of
+OpenSSL doesn't conflict with Python's.
+
+The options you need to add allow the linker to identify every symbol correctly
+even when multiple versions of the library are linked into the same program. If
+you are using your distribution's source packages these will probably be
+patched in for you already, otherwise you'll need to use options something like
+this when configuring OpenSSL:
+
+.. code-block:: console
+
+    $ ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared
+
+You'll also need to generate your own ``openssl.ld`` file. For example::
+
+    OPENSSL_1.0.1F_CUSTOM {
+        global:
+            *;
+    };
+
+You should replace the version string on the first line as appropriate for your
+build.
+
+Using your own OpenSSL on OS X
+------------------------------
+
+To link cryptography against a custom version of OpenSSL you'll need to set
+``ARCHFLAGS``, ``LDFLAGS``, and ``CFLAGS``. OpenSSL can be installed via
+`Homebrew`_:
+
+.. code-block:: console
+
+    $ brew install openssl
+
+Then install cryptography linking against the brewed version:
+
+.. code-block:: console
+
+    $ env ARCHFLAGS="-arch x86_64" LDFLAGS="-L/usr/local/opt/openssl/lib" CFLAGS="-I/usr/local/opt/openssl/include" pip install cryptography
+
+
+.. _`Homebrew`: http://brew.sh
+.. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html