RFC for docs

docs/notebooks/pyUmbral Simple API.ipynb

@@ -176,12 +176,12 @@
     "from umbral import generate_kfrags\n",
     "\n",
     "\n",
-    "M, N = 10, 20\n",
+    "M, N = 10, 20 # the threshold and the total number of fragments\n",
     "kfrags = generate_kfrags(delegating_sk=alices_private_key,\n",
     "                         receiving_pk=bobs_public_key,\n",
     "                         signing_sk=alices_signing_key,\n",
-    "                         threshold=10,\n",
-    "                         num_kfrags=20)"
+    "                         threshold=M,\n",
+    "                         num_kfrags=N)"
    ]
   },
   {
@@ -201,7 +201,7 @@
    "source": [
     "import random\n",
     "kfrags = random.sample(kfrags,  # All kfrags from above\n",
-    "                       10)      # M - Threshold\n",
+    "                       M)       # Threshold\n",
     "\n",
     "\n",
     "from umbral import reencrypt\n",
@@ -210,9 +210,7 @@
     "cfrags = list()                 # Bob's cfrag collection\n",
     "for kfrag in kfrags:\n",
     "    cfrag = reencrypt(capsule=capsule, kfrag=kfrag)\n",
-    "    cfrags.append(cfrag)        # Bob collects a cfrag\n",
-    "\n",
-    "assert len(cfrags) == 10\n"
+    "    cfrags.append(cfrag)        # Bob collects a cfrag"
    ]
   },
   {
@@ -243,7 +241,7 @@
    "metadata": {},
    "source": [
     "## Bob opens the capsule; Decrypts data from Alice.\n",
-    "Finally, Bob decrypts the re-encrypted ciphertext using his key."
+    "Finally, Bob decrypts the re-encrypted ciphertext using his secret key."
    ]
   },
   {

docs/source/index.rst

@@ -31,7 +31,7 @@ pyUmbral
 .. end-badges
 
 pyUmbral is the reference implementation of the Umbral_ threshold proxy re-encryption scheme.
-It is open-source, built with Python, and uses OpenSSL_ via Cryptography.io_ and libsodium_ via PyNaCl_.
+It is open-source, built with Python, and uses OpenSSL_ via Cryptography.io_, and libsodium_ via PyNaCl_.
 
 Using Umbral, Alice (the data owner) can *delegate decryption rights* to Bob for
 any ciphertext intended to her, through a re-encryption process performed by a

docs/source/using_pyumbral.rst

@@ -23,7 +23,9 @@ You can find them in the ``cryptography.hazmat.primitives.asymmetric.ec`` module
 
 .. _Cryptography.io: https://cryptography.io/en/latest/
 
-Be careful when choosing a curve - the security of your application depends on it.
+.. important::
+
+    Be careful when choosing a curve - the security of your application depends on it.
 
 We provide curve ``SECP256K1`` as a default because it is the basis for a number of crypto-blockchain projects;
 we don't otherwise endorse its security.
@@ -89,7 +91,7 @@ Bob Exists
 
 Alice grants access to Bob by generating kfrags
 -----------------------------------------------
-When Alice wants to grant Bob access to open her encrypted messages,
+When Alice wants to grant Bob access to view her encrypted data,
 she creates *re-encryption key fragments*, or *"kfrags"*,
 which are next sent to N proxies or *Ursulas*.