diff --git a/doc/api.rst b/doc/api.rst
index 55a33ec..826ec4d 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -1,16 +1,15 @@
+.. _openssl:
+
+:py:mod:`OpenSSL` --- Python interface to OpenSSL
+=================================================
+
 .. py:module:: OpenSSL
+   :synopsis: Python interface to OpenSSL
 
 
-.. _api-openssl:
-
-
-OpenSSL -- Python interface to OpenSSL
-======================================
-
 This package provides a high-level interface to the functions in the
 OpenSSL library. The following modules are defined:
 
-
 .. toctree::
    :maxdepth: 2
 
diff --git a/doc/api/crypto.rst b/doc/api/crypto.rst
index 907bdf5..f1486f1 100644
--- a/doc/api/crypto.rst
+++ b/doc/api/crypto.rst
@@ -1,9 +1,10 @@
+.. _openssl-crypto:
+
+:py:mod:`crypto` --- Generic cryptographic module
+=================================================
+
 .. py:module:: OpenSSL.crypto
-
-.. _api-openssl-crypto:
-
-``crypto`` -- Generic cryptographic module
-==========================================
+   :synopsis: Generic cryptographic module
 
 
 .. py:data:: X509Type
@@ -102,13 +103,13 @@
 
 
 .. py:data:: FILETYPE_PEM
-.. py:data:: FILETYPE_ASN1
+             FILETYPE_ASN1
 
     File type constants.
 
 
 .. py:data:: TYPE_RSA
-.. py:data:: TYPE_DSA
+             TYPE_DSA
 
     Key type constants.
 
@@ -250,9 +251,9 @@
     Return a string giving the time before which the certificate is not valid.  The
     string is formatted as an ASN1 GENERALIZEDTIME::
 
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
+        YYYYMMDDhhmmssZ
+        YYYYMMDDhhmmss+hhmm
+        YYYYMMDDhhmmss-hhmm
 
     If no value exists for this field, :py:data:`None` is returned.
 
@@ -262,9 +263,9 @@
     Return a string giving the time after which the certificate is not valid.  The
     string is formatted as an ASN1 GENERALIZEDTIME::
 
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
+        YYYYMMDDhhmmssZ
+        YYYYMMDDhhmmss+hhmm
+        YYYYMMDDhhmmss-hhmm
 
     If no value exists for this field, :py:data:`None` is returned.
 
@@ -274,9 +275,9 @@
     Change the time before which the certificate is not valid.  *when* is a
     string formatted as an ASN1 GENERALIZEDTIME::
 
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
+        YYYYMMDDhhmmssZ
+        YYYYMMDDhhmmss+hhmm
+        YYYYMMDDhhmmss-hhmm
 
 
 .. py:method:: X509.set_notAfter(when)
@@ -284,9 +285,9 @@
     Change the time after which the certificate is not valid.  *when* is a
     string formatted as an ASN1 GENERALIZEDTIME::
 
-                 YYYYMMDDhhmmssZ
-                 YYYYMMDDhhmmss+hhmm
-                 YYYYMMDDhhmmss-hhmm
+        YYYYMMDDhhmmssZ
+        YYYYMMDDhhmmss+hhmm
+        YYYYMMDDhhmmss-hhmm
 
 
 
@@ -504,23 +505,23 @@
 
 The PKey object has the following methods:
 
-.. py:method:: Pkey.bits()
+.. py:method:: PKey.bits()
 
     Return the number of bits of the key.
 
 
-.. py:method:: Pkey.generate_key(type, bits)
+.. py:method:: PKey.generate_key(type, bits)
 
     Generate a public/private key pair of the type *type* (one of
     :py:const:`TYPE_RSA` and :py:const:`TYPE_DSA`) with the size *bits*.
 
 
-.. py:method:: Pkey.type()
+.. py:method:: PKey.type()
 
     Return the type of the key.
 
 
-.. py:method:: Pkey.check()
+.. py:method:: PKey.check()
 
     Check the consistency of this key, returning True if it is consistent and
     raising an exception otherwise.  This is only valid for RSA keys.  See the
@@ -534,27 +535,27 @@
 
 PKCS7 objects have the following methods:
 
-.. py:method:: Pkey.type_is_signed()
+.. py:method:: PKCS7.type_is_signed()
 
     FIXME
 
 
-.. py:method:: Pkey.type_is_enveloped()
+.. py:method:: PKCS7.type_is_enveloped()
 
     FIXME
 
 
-.. py:method:: Pkey.type_is_signedAndEnveloped()
+.. py:method:: PKCS7.type_is_signedAndEnveloped()
 
     FIXME
 
 
-.. py:method:: Pkey.type_is_data()
+.. py:method:: PKCS7.type_is_data()
 
     FIXME
 
 
-.. py:method:: Pkey.get_type_name()
+.. py:method:: PKCS7.get_type_name()
 
     Get the type name of the PKCS7.
 
@@ -566,7 +567,7 @@
 
 PKCS12 objects have the following methods:
 
-.. py:method:: PKCS12.export([passphrase=None[, iter=2048][, maciter=1])
+.. py:method:: PKCS12.export([passphrase=None][, iter=2048][, maciter=1])
 
     Returns a PKCS12 object as a string.
 
diff --git a/doc/api/rand.rst b/doc/api/rand.rst
index b531254..18789b8 100644
--- a/doc/api/rand.rst
+++ b/doc/api/rand.rst
@@ -1,9 +1,11 @@
+.. _openssl-rand:
+
+:py:mod:`rand` --- An interface to the OpenSSL pseudo random number generator
+=============================================================================
+
 .. py:module:: OpenSSL.rand
+   :synopsis: An interface to the OpenSSL pseudo random number generator
 
-.. _api-openssl-rand:
-
-``rand`` -- An interface to the OpenSSL pseudo random number generator
-======================================================================
 
 This module handles the OpenSSL pseudo random number generator (PRNG) and
 declares the following:
@@ -31,9 +33,9 @@
 
 .. py:function:: egd(path[, bytes])
 
-    Query the Entropy Gathering Daemon [#entropy-gathering-daemon]_ on socket
-    *path* for *bytes* bytes of random data and uses :py:func:`add` to seed
-    the PRNG. The default value of *bytes* is 255.
+    Query the `Entropy Gathering Daemon <http://www.lothar.com/tech/crypto/>`_ on
+    socket *path* for *bytes* bytes of random data and uses :py:func:`add` to
+    seed the PRNG. The default value of *bytes* is 255.
 
 
 .. py:function:: load_file(path[, bytes])
@@ -75,6 +77,3 @@
     from the OpenSSL error queue, where each item is a tuple *(lib, function,
     reason)*. Here *lib*, *function* and *reason* are all strings, describing
     where and what the problem is. See :manpage:`err(3)` for more information.
-
-
-.. [#entropy-gathering-daemon] See http://www.lothar.com/tech/crypto/.
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst
index 76bb981..7c1bc3d 100644
--- a/doc/api/ssl.rst
+++ b/doc/api/ssl.rst
@@ -1,42 +1,44 @@
+.. _openssl-ssl:
+
+:py:mod:`SSL` --- An interface to the SSL-specific parts of OpenSSL
+===================================================================
+
 .. py:module:: OpenSSL.SSL
+    :synopsis: An interface to the SSL-specific parts of OpenSSL
 
-.. _api-openssl-ssl:
-
-``SSL`` -- An interface to the SSL-specific parts of OpenSSL
-============================================================
 
 This module handles things specific to SSL. There are two objects defined:
 Context, Connection.
 
 .. py:data:: SSLv2_METHOD
-.. py:data:: SSLv3_METHOD
-.. py:data:: SSLv23_METHOD
-.. py:data:: TLSv1_METHOD
+             SSLv3_METHOD
+             SSLv23_METHOD
+             TLSv1_METHOD
 
     These constants represent the different SSL methods to use when creating a
     context object.
 
 
 .. py:data:: VERIFY_NONE
-.. py:data:: VERIFY_PEER
-.. py:data:: VERIFY_FAIL_IF_NO_PEER_CERT
+             VERIFY_PEER
+             VERIFY_FAIL_IF_NO_PEER_CERT
 
     These constants represent the verification mode used by the Context
     object's :py:meth:`set_verify` method.
 
 
 .. py:data:: FILETYPE_PEM
-.. py:data:: FILETYPE_ASN1
+             FILETYPE_ASN1
 
     File type constants used with the :py:meth:`use_certificate_file` and
     :py:meth:`use_privatekey_file` methods of Context objects.
 
 
 .. py:data:: OP_SINGLE_DH_USE
-.. py:data:: OP_EPHEMERAL_RSA
-.. py:data:: OP_NO_SSLv2
-.. py:data:: OP_NO_SSLv3
-.. py:data:: OP_NO_TLSv1
+             OP_EPHEMERAL_RSA
+             OP_NO_SSLv2
+             OP_NO_SSLv3
+             OP_NO_TLSv1
 
     Constants used with :py:meth:`set_options` of Context objects.
 
@@ -50,10 +52,10 @@
 
 
 .. py:data:: SSLEAY_VERSION
-.. py:data:: SSLEAY_CFLAGS
-.. py:data:: SSLEAY_BUILT_ON
-.. py:data:: SSLEAY_PLATFORM
-.. py:data:: SSLEAY_DIR
+             SSLEAY_CFLAGS
+             SSLEAY_BUILT_ON
+             SSLEAY_PLATFORM
+             SSLEAY_DIR
 
     Constants used with :py:meth:`SSLeay_version` to specify what OpenSSL version
     information to retrieve.  See the man page for the :py:func:`SSLeay_version` C
@@ -242,7 +244,7 @@
     Specify where CA certificates for verification purposes are located. These
     are trusted certificates. Note that the certificates have to be in PEM
     format.  If capath is passed, it must be a directory prepared using the
-    ``_rehash`` tool included with OpenSSL.  Either, but not both, of
+    ``c_rehash`` tool included with OpenSSL.  Either, but not both, of
     *pemfile* or *capath* may be :py:data:`None`.
 
 
@@ -274,9 +276,9 @@
     Set the information callback to *callback*. This function will be called
     from time to time during SSL handshakes.
 
-    *callback* should take three arguments: a Connection object and two
-    integers. The first integer specifies where in the SSL handshake the function
-    was called, and the other the return code from a (possibly failed) internal
+    *callback* should take three arguments: a Connection object and two integers.
+    The first integer specifies where in the SSL handshake the function was
+    called, and the other the return code from a (possibly failed) internal
     function call.
 
 
@@ -374,8 +376,9 @@
 .. py:method:: Context.set_tlsext_servername_callback(callback)
 
     Specify a one-argument callable to use as the TLS extension server name
-    callback.  When a connection using the server name extension is made using this
-    context, the callback will be invoked with the \code{Connection} instance.
+    callback.  When a connection using the server name extension is made using
+    this context, the callback will be invoked with the :py:class:`Connection`
+    instance.
 
     .. versionadded:: 0.13
 
@@ -653,6 +656,8 @@
     .. versionadded:: 0.13
 
 
+.. Rubric:: Footnotes
+
 .. [#connection-context-socket] Actually, all that is required is an object that
     **behaves** like a socket, you could even use files, even though it'd be
     tricky to get the handshakes right!
diff --git a/doc/index.rst b/doc/index.rst
index 8f1d336..a63df87 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -1,14 +1,12 @@
-.. pyOpenSSL documentation master file, created by
-   sphinx-quickstart on Sat Jul 16 07:12:22 2011.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to pyOpenSSL's documentation!
 =====================================
 
-This module is a rather thin wrapper around (a subset of) the OpenSSL library.
-With thin wrapper I mean that a lot of the object methods do nothing more than
-calling a corresponding function in the OpenSSL library.
+.. topic:: Abstract
+
+   This module is a rather thin wrapper around (a subset of) the OpenSSL library.
+   With thin wrapper I mean that a lot of the object methods do nothing more than
+   calling a corresponding function in the OpenSSL library.
+
 
 Contents:
 
diff --git a/doc/install.rst b/doc/install.rst
index fc3c348..f525726 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -3,7 +3,6 @@
 Building and Installing
 =======================
 
-
 These instructions can also be found in the file ``INSTALL``.
 
 I have tested this on Debian Linux systems (woody and sid), Solaris 2.6 and
diff --git a/doc/internals.rst b/doc/internals.rst
index 8b1c9f6..839c446 100644
--- a/doc/internals.rst
+++ b/doc/internals.rst
@@ -53,7 +53,7 @@
 (using Python's own TLS API, :c:func:`PyThread_set_key_value`).  When it is
 necessary to re-acquire the GIL, either after the OpenSSL API returns or in a C
 callback invoked by that OpenSSL API, the value of the thread local variable is
-retrieved (:c:func`PyThread_get_key_value`) and used to re-acquire the GIL.
+retrieved (:c:func:`PyThread_get_key_value`) and used to re-acquire the GIL.
 This allows Python threads to execute while OpenSSL APIs are running and allows
 use of any particular pyOpenSSL object from any Python thread, since there is
 no per-thread state associated with any of these objects and since OpenSSL is