Merge pull request #2142 from alex/x509-tutorial

Reorganize the x509 docs in prep for a tutorial
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index 475a2a3..85f8447 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -93,7 +93,7 @@
   Note that unsupported extensions with the critical flag raise
   :class:`~cryptography.x509.UnsupportedExtension` while unsupported extensions
   set to non-critical are silently ignored. Read the
-  :doc:`X.509 documentation</x509>` for more information.
+  :doc:`X.509 documentation</x509/index>` for more information.
 
 0.8.2 - 2015-04-10
 ~~~~~~~~~~~~~~~~~~
@@ -120,7 +120,7 @@
   from :mod:`~cryptography.hazmat.primitives.interfaces` to
   :mod:`~cryptography.hazmat.primitives.kdf`.
 * Added support for parsing X.509 names. See the
-  :doc:`X.509 documentation</x509>` for more information.
+  :doc:`X.509 documentation</x509/index>` for more information.
 * Added
   :func:`~cryptography.hazmat.primitives.serialization.load_der_private_key` to
   support loading of DER encoded private keys and
@@ -256,7 +256,7 @@
   support the loading of OpenSSH public keys (:rfc:`4253`). Only RSA and DSA
   keys are currently supported.
 * Added initial support for X.509 certificate parsing. See the
-  :doc:`X.509 documentation</x509>` for more information.
+  :doc:`X.509 documentation</x509/index>` for more information.
 
 0.6.1 - 2014-10-15
 ~~~~~~~~~~~~~~~~~~
diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst
index 7839f34..8d51f0d 100644
--- a/docs/hazmat/primitives/asymmetric/serialization.rst
+++ b/docs/hazmat/primitives/asymmetric/serialization.rst
@@ -97,8 +97,8 @@
 .. note::
 
     A PEM block which starts with ``-----BEGIN CERTIFICATE-----`` is not a
-    public or private key, it's an :doc:`X.509 Certificate </x509>`. You can
-    load it using :func:`~cryptography.x509.load_pem_x509_certificate` and
+    public or private key, it's an :doc:`X.509 Certificate </x509/index>`. You
+    can load it using :func:`~cryptography.x509.load_pem_x509_certificate` and
     extract the public key with
     :meth:`Certificate.public_key <cryptography.x509.Certificate.public_key>`.
 
diff --git a/docs/index.rst b/docs/index.rst
index 35f80a2..5c26a75 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -63,7 +63,7 @@
     :maxdepth: 2
 
     fernet
-    x509
+    x509/index
     random-numbers
     exceptions
     faq
diff --git a/docs/x509/index.rst b/docs/x509/index.rst
new file mode 100644
index 0000000..c3fa1ed
--- /dev/null
+++ b/docs/x509/index.rst
@@ -0,0 +1,14 @@
+X.509
+=====
+
+X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
+defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509
+certificates are commonly used in protocols like `TLS`_.
+
+.. toctree::
+    :maxdepth: 2
+
+    reference
+
+.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
+.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security
diff --git a/docs/x509.rst b/docs/x509/reference.rst
similarity index 98%
rename from docs/x509.rst
rename to docs/x509/reference.rst
index bcb6ee6..9179468 100644
--- a/docs/x509.rst
+++ b/docs/x509/reference.rst
@@ -1,5 +1,5 @@
-X.509
-=====
+X.509 Reference
+===============
 
 .. currentmodule:: cryptography.x509
 
@@ -86,10 +86,6 @@
     -----END CERTIFICATE-----
     """.strip()
 
-X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is
-defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509
-certificates are commonly used in protocols like `TLS`_.
-
 Loading Certificates
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -1582,7 +1578,5 @@
         types can be found in `RFC 5280 section 4.2.1.6`_.
 
 
-.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure
-.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security
 .. _`RFC 5280 section 4.2.1.1`: https://tools.ietf.org/html/rfc5280#section-4.2.1.1
 .. _`RFC 5280 section 4.2.1.6`: https://tools.ietf.org/html/rfc5280#section-4.2.1.6