Docs: fix some grammar and sphinx linking (#209)

* Small grammar and consistency changes for docs

* Fix broken link and internal project reference in docs

docs/public.rst

@@ -46,33 +46,33 @@ This is how the system works:
     import nacl.utils
     from nacl.public import PrivateKey, Box
 
-    # generate the private key which must be kept secret
+    # Generate Bob's private key, which must be kept secret
     skbob = PrivateKey.generate()
 
-    # the public key can be given to anyone wishing to send
-    # Bob an encrypted message
+    # Bob's public key can be given to anyone wishing to send
+    #   Bob an encrypted message
     pkbob = skbob.public_key
 
-    # Alice does the same and then
-    #     sends her public key to Bob and Bob his public key to Alice
+    # Alice does the same and then Alice and Bob exchange public keys
     skalice = PrivateKey.generate()
     pkalice = skalice.public_key
 
-    # Bob wishes to send Alice an encrypted message
-    # So Bob must make a Box with his private key and Alice's public key
+    # Bob wishes to send Alice an encrypted message so Bob must make a Box with
+    #   his private key and Alice's public key
     bob_box = Box(skbob, pkalice)
 
-    # This is our message to send, it must be a bytestring as Box will
-    #   treat is as just a binary blob of data.
+    # This is our message to send, it must be a bytestring as Box will treat it
+    #   as just a binary blob of data.
     message = b"Kill all humans"
 
     # This is a nonce, it *MUST* only be used once, but it is not considered
     #   secret and can be transmitted or stored alongside the ciphertext. A
-    #   good source of nonce is just 24 random bytes.
+    #   good source of nonces are just sequences of 24 random bytes.
     nonce = nacl.utils.random(Box.NONCE_SIZE)
 
-    # Encrypt our message, it will be exactly 40 bytes longer than the original
-    #   message as it stores authentication information and nonce alongside it.
+    # Encrypt our message, it will be exactly 40 bytes longer than the
+    #   original message as it stores authentication information and the
+    #   nonce alongside it.
     encrypted = bob_box.encrypt(message, nonce)
 
     # Alice creates a second box with her private key to decrypt the message

docs/secret.rst

@@ -9,7 +9,7 @@ open it and view the contents. :class:`~nacl.secret.SecretBox` functions as
 just such a safe, and like any good safe any attempts to tamper with the
 contents is easily detected.
 
-Secret Key Encryption allows you to store or transmit data over insecure
+Secret key encryption allows you to store or transmit data over insecure
 channels without leaking the contents of that message, nor anything about it
 other than the length.
 
@@ -28,16 +28,17 @@ Example
     box = nacl.secret.SecretBox(key)
 
     # This is our message to send, it must be a bytestring as SecretBox will
-    #   treat is as just a binary blob of data.
+    #   treat it as just a binary blob of data.
     message = b"The president will be exiting through the lower levels"
 
     # This is a nonce, it *MUST* only be used once, but it is not considered
     #   secret and can be transmitted or stored alongside the ciphertext. A
-    #   good source of nonce is just 24 random bytes.
+    #   good source of nonces are just sequences of 24 random bytes.
     nonce = nacl.utils.random(nacl.secret.SecretBox.NONCE_SIZE)
 
-    # Encrypt our message, it will be exactly 40 bytes longer than the original
-    #   message as it stores authentication information and nonce alongside it.
+    # Encrypt our message, it will be exactly 40 bytes longer than the
+    #   original message as it stores authentication information and the
+    #   nonce alongside it.
     encrypted = box.encrypt(message, nonce)
 
     # Decrypt our message, an exception will be raised if the encryption was
@@ -81,7 +82,7 @@ reason, many protocols derive a new key for each session, reset the counter
 to zero with each new key, and never store the derived key or the counter.
 
 You can safely generate random nonces by calling
-:func:`~nacl.utils.random(SecretBox.NONCE_SIZE)`.
+:func:`~nacl.utils.random` with ``SecretBox.NONCE_SIZE``.
 
 
 Reference

docs/signing.rst

@@ -185,7 +185,7 @@ Ed25519 is a public-key signature system with several attractive features:
   of tied to an entropy source.
 
 The numbers 87548 and 273364 shown above are official
-`eBATS <http://bench.cr.yp.to/>` reports for a Westmere CPU (Intel Xeon E5620,
+`eBATS <http://bench.cr.yp.to/>`_ reports for a Westmere CPU (Intel Xeon E5620,
 hydra2).
 
 Ed25519 signatures are elliptic-curve signatures, carefully engineered at