Added canonical installation document with details about various platforms, fixes #519
diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst
index 926ec7d..12d2d9f 100644
--- a/docs/hazmat/backends/openssl.rst
+++ b/docs/hazmat/backends/openssl.rst
@@ -13,52 +13,4 @@
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 b800bca..73c40bf 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,30 +5,6 @@
primitives. We hope it'll be your one-stop-shop for all your cryptographic
needs in Python.
-Installing
-----------
-
-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
-
-
Why a new crypto library for Python?
------------------------------------
@@ -64,6 +40,13 @@
We recommend using the recipes layer whenever possible, and falling back to the
hazmat layer only when necessary.
+Installation
+~~~~~~~~~~~~
+.. toctree::
+ :maxdepth: 2
+
+ installation
+
The recipes layer
~~~~~~~~~~~~~~~~~
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..d9c3080
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,76 @@
+Installing
+==========
+
+You can install ``cryptography`` with ``pip``:
+
+.. code-block:: console
+
+ $ pip install cryptography
+
+Installation Notes
+==================
+On Windows
+----------
+.. 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
+
+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