Add Jupyter Notebook Support (#450)

* Add Jupyter Notebook Support

* Add mkdocs-jupyter dependency

* Add dependency for mkdocs-jupyter

* 📝. Add Configure Election as Jupyter Notebook

- Remove excess items in poetry lock
- Add mkdocs-jupyter and underlying dependencies
- Convert 0_Configure_Election to Jupyter notebook

Co-authored-by: Keith Fung <[email protected]>
Co-authored-by: Keith Fung <[email protected]>

Author: abxhr

Makefile

@@ -147,6 +147,7 @@ bench:
 # Documentation
 install-mkdocs:
 	pip install mkdocs
+	pip install mkdocs-jupyter
 
 docs-serve:
 	mkdocs serve

docs/0_Configure_Election.ipynb

@@ -0,0 +1,100 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# Election Configuration\n",
+    "\n",
+    "An election in ElectionGuard is defined as a set of metadata and cryptographic artifacts necessary to encrypt, conduct, tally, decrypt, and verify an election. The Data format used for election metadata is based on the [NIST Election Common Standard Data Specification](https://www.nist.gov/itl/voting/interoperability) but includes some modifications to support the end-to-end cryptography of ElectionGuard.\n",
+    "\n",
+    "Election metadata is described in a specific format parseable into an `Manifest` and it's validity is checked to ensure that it is of an appropriate structure to conduct an End-to-End Verified ElectionGuard Election. ElectionGuard only verifies the components of the election metadata that are necessary to encrypt and decrypt the election. Some components of the election metadata are not checked for structural validity, but are used when generating a hash representation of the `Manifest`.\n",
+    "\n",
+    "From an `Manifest` we derive an `InternalManifest` that includes a subset of the elements from the `Manifest` required to verify ballots are correct. Additionally a `CiphertextElectionContext` is created during the [Key Ceremony](/1_Key_Ceremony.md) that includes the cryptographic artifacts necessary for encrypting ballots.\n",
+    "\n",
+    "## Glossary\n",
+    "\n",
+    "- **Election Manifest** The election metadata in json format that is parsed into an Election Description\n",
+    "- **Election Description** The election metadata that describes the structure and type of the election, including geopolitical units, contests, candidates, and ballot styles, etc.\n",
+    "- **Internal Election Description** The subset of the `Manifest` required by ElectionGuard to validate ballots are correctly associated with an election. This component mutates the state of the Election Description.\n",
+    "- **Ciphertext Election Context** The cryptographic context of an election that is configured during the `Key Ceremony`\n",
+    "- **Description Hash** a Hash representation of the original Manifest.\n",
+    "\n",
+    "## Process\n",
+    "\n",
+    "1. Define an election according to the `Manifest` requirements.\n",
+    "2. Use the [NIST Common Standard Data Specification](https://www.nist.gov/itl/voting/interoperability) as a guide, but note the differences in [election.py](https://github.com/microsoft/electionguard-python/tree/main/src/electionguard.election.py) and the provided [sample manifest](https://github.com/microsoft/electionguard-python/tree/main/data/election_manifest_simple.json).\n",
+    "3. Parse the `Manifest` into the application.\n",
+    "4. Define the encryption parameters necessary for conducting an election (see `Key Ceremony`).\n",
+    "5. Create the Pubic Key either from a single secret, or from the Key Ceremony.\n",
+    "6. Build the `InternalManifest` and `CiphertextElectionContext` from the `Manifest` and `ElGamalKeyPair.public_key`.\n",
+    "\n",
+    "## Usage Example"
+   ],
+   "metadata": {}
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "source": [
+    "\n",
+    "import os\n",
+    "from electionguard.election import CiphertextElectionContext\n",
+    "from electionguard.election_builder import ElectionBuilder\n",
+    "from electionguard.elgamal import ElGamalKeyPair, elgamal_keypair_from_secret\n",
+    "from electionguard.manifest import Manifest, InternalManifest\n",
+    "\n",
+    "# Open an election manifest file\n",
+    "with open(os.path.join(some_path, \"election-manifest.json\"), \"r\") as manifest:\n",
+    "        string_representation = manifest.read()\n",
+    "        election_description = Manifest.from_json(string_representation)\n",
+    "\n",
+    "# Create an election builder instance, and configure it for a single public-private keypair.\n",
+    "# in a real election, you would configure this for a group of guardians.  See Key Ceremony for more information.\n",
+    "builder = ElectionBuilder(\n",
+    "    number_of_guardians=1,     # since we will generate a single public-private keypair, we set this to 1\n",
+    "    quorum=1,                  # since we will generate a single public-private keypair, we set this to 1\n",
+    "    description=election_description\n",
+    ")\n",
+    "\n",
+    "# Generate an ElGamal Keypair from a secret.  In a real election you would use the Key Ceremony instead.\n",
+    "some_secret_value: int = 12345\n",
+    "keypair: ElGamalKeyPair = elgamal_keypair_from_secret(some_secret_value)\n",
+    "\n",
+    "builder.set_public_key(keypair.public_key)\n",
+    "\n",
+    "# get an `InternalElectionDescription` and `CiphertextElectionContext`\n",
+    "# that are used for the remainder of the election.\n",
+    "(internal_manifest, context) = builder.build()"
+   ],
+   "outputs": [],
+   "metadata": {
+    "attributes": {
+     "classes": [
+      "code-cell"
+     ],
+     "id": ""
+    }
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Constants\n",
+    "\n",
+    "The election constants are the four constants that sit underneath most of the mathematical operations. The election constants can be configured, but there is a standard set which is recommended for most use cases. These can be found in `constants.py`.\n",
+    "\n",
+    "**⚠️ Warning ⚠️**\n",
+    "\n",
+    "There are some test constants used for testing code, but these are never to be used in any production system. The small and extra small constants are unlikely to be used except in rare cases for property testing due to collisions that will happen for smaller number sets."
+   ],
+   "metadata": {}
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/0_Configure_Election.md

@@ -72,7 +72,7 @@ Sections:
 
 Step-by-Step Process:
 
-0. [Configure Election](0_Configure_Election.md)
+0. [Configure Election](0_Configure_Election.ipynb)
 1. [Key Ceremony](1_Key_Ceremony.md)
 2. [Encrypt Ballots](2_Encrypt_Ballots.md)
 3. [Cast and Spoil](3_Cast_and_Spoil.md)

docs/index.md

@@ -2,23 +2,25 @@ site_name: ElectionGuard Python
 site_url: https://electionguard-python.readthedocs.io/
 # site_description:
 site_author: Microsoft
-# google_analytics: 
+# google_analytics:
 # remote_branch: for gh-deploy to GithubPages
 # remote_name: for gh-deploy to Github Pages
-copyright: '© Microsoft 2020'
-docs_dir: 'docs'
+copyright: "© Microsoft 2020"
+docs_dir: "docs"
 repo_url: https://github.com/microsoft/electionguard-python/
 nav:
-    - Home: index.md
-    - Design and Architecture: Design_and_Architecture.md
-    - Build and Run: Build_and_Run.md
-    - Project Workflow: Project_Workflow.md
-    - Election Manifest: Election_Manifest.md
-    - Steps:
-        - 0. Configure Election: 0_Configure_Election.md
-        - 1. Key Ceremony: 1_Key_Ceremony.md
-        - 2. Encrypt Ballots: 2_Encrypt_Ballots.md
-        - 3. Cast and Spoil: 3_Cast_and_Spoil.md
-        - 4. Decrypt Tally: 4_Decrypt_Tally.md
-        - 5. Publish and Verify: 5_Publish_and_Verify.md
-theme: readthedocs
+  - Home: index.md
+  - Design and Architecture: Design_and_Architecture.md
+  - Build and Run: Build_and_Run.md
+  - Project Workflow: Project_Workflow.md
+  - Election Manifest: Election_Manifest.md
+  - Steps:
+      - 0. Configure Election: 0_Configure_Election.ipynb
+      - 1. Key Ceremony: 1_Key_Ceremony.md
+      - 2. Encrypt Ballots: 2_Encrypt_Ballots.md
+      - 3. Cast and Spoil: 3_Cast_and_Spoil.md
+      - 4. Decrypt Tally: 4_Decrypt_Tally.md
+      - 5. Publish and Verify: 5_Publish_and_Verify.md
+theme: readthedocs
+plugins:
+  - mkdocs-jupyter