Complete several of the utility documents for Jupyter

docs/notebooks/documents/getting_started.py

@@ -13,64 +13,15 @@
 # ---
 
 # %% [markdown]
-# # Getting Started
+# # Managing the PDO Environment
 #
-# This document provides an overview for preparing to work with PDO contracts through the contract
-# docker container. It will walk through the necessary steps to set up a functional
-# configuration. It does assume that the reader is familiar with
+# This notebook provides an aggregate interface for preparing to work with PDO contracts through the
+# necessary steps to set up a functional configuration. It assumes that the reader is familiar with
 # [basic operation of Jupyter notebooks](https://jupytext.readthedocs.io/en/latest/).
 #
-# %% [markdown]
-# ## How Contracts Use Jupyter
-#
-# Many of the PDO contract families provide Jupyter notebooks to simplify interaction with contract
-# objects. Commonly, the notebooks provide a factory for instantiating a notebook for each new
-# contract from one of the contract specific templates. The templates provided generally include five
-# common sections:
-#
-# * Configure the Contract Object
-# * Initialize the Jupyter Interpreter and the PDO Environment
-# * Initialize the Contract Object Context
-# * Operate on the Contract
-# * View Contract Metadata
-#
-# *Configure the Contract Object*: Each notebook either loads an existing contract object from a
-# file (see the PDO documentation on contract collections) or creates a new contract object based on
-# an initial set of parameters. To create a new contract object, a factory will collect input that
-# is used to instantiate a template notebook with the set of required parameters.
-#
-# *Initialize the Jupyter Interpreter and PDO Environment*: To initialize the Jupyter interpreter,
-# the notebook loads the Juptyer helper module. This module imports all of the relevant PDO and
-# Jupyter IPython modules to simplify code in the notebook. It also defines several procedures that
-# are useful for initializing and interacting with the PDO environment.
-#
-# In addition, the Jupyter interpreter initialization configures an IPython extension that makes it
-# easier to provide code for multiple types of operations that can be performed on the contract
-# object. Specifically, the extension defines a magic keyword, `skip`, that takes a value or
-# expression that, if it evaluates to True, causes the code section to be skipped during notebook
-# execution.
-#
-# *Initialize the Contract Object Context*: The next section in the notebook creates a PDO context
-# for the contract object (see the PDO documentation for more information on contexts).  The context
-# includes all information necessary to create the contract object (and its dependencies) based on
-# the initial set of parameters provided by the factory notebook. Beyond the initial parameters, the
-# context allows for fine-grained customization of the contract object, though the defaults are
-# usually sufficient.
-#
-# *Operate on the Contract*: The contract object may be used once it has been created and
-# initialized. In general, cells in this section of the notebook are turned off by default; that is,
-# `%%skip True` is added at the top of the cell. To perform an operation, change the top line to
-# `%%skip False` and evaluate the cell.
-#
-# *View Contract Metadata*: For the curious (and those debugging contract behavior), the final
-# section of most notebooks includes a section to examine the metadata associated with a contract.
-
-# %% [markdown]
-# ## Configure the PDO Environment
-#
-# The remainder of this notebook helps to setup and verify the PDO environment in which the
-# notebooks operate. If you have started the Jupyter Lab server through the docker test interface, a
-# basic environment has already been created that is sufficient for working with the notebooks.
+# This notebook helps to setup and verify the PDO environment in which the notebooks operate. If you
+# have started the Jupyter Lab server through the PDO contracts docker test interface, a basic
+# environment has already been created that is sufficient for working with the notebooks.
 # Otherwise, you may use the sections of this notebook to create or import signing keys for
 # transactions, configure PDO services (e.g. by importing a PDO `site.toml` file), and configure
 # service groups to simplify contract creation.
@@ -101,18 +52,25 @@
 # Additional management of keys is provided by the [Key Manager Notebook](key_manager.ipynb).
 #
 # %%
-from pdo.contracts.keys import PrivateKeyListWidget, GenerateKeyWidget
+from pdo.contracts.keys import PrivateKeyListWidget
+from pdo.contracts.keys import PublicKeyListWidget
+from pdo.contracts.keys import GenerateKeyWidget
+from pdo.contracts.keys import UploadKeyWidget
 
-key_list = PrivateKeyListWidget(state, bindings)
-key_gen = GenerateKeyWidget(state, bindings)
-ip_display.display(ipywidgets.VBox([key_list, key_gen]))
+private_key_list = PrivateKeyListWidget(state, bindings)
+public_key_list = PublicKeyListWidget(state, bindings)
+key_generate = GenerateKeyWidget(state, bindings)
+key_import = UploadKeyWidget(state, bindings)
 
+children = [public_key_list, private_key_list, key_generate, key_import]
+titles = ['Public Key List', 'Private Key List', 'Generate Key Pair', 'Import Keys']
+ip_display.display(ipywidgets.Tab(children=children, titles=titles))
 # %% [markdown]
 # ## Import Site Information
 #
 # PDO clients require information about the services that will be used for contracts. Typically, a
 # service provider will create a site description file (often called `site.toml`) that can be used
-# to import information about a number of services.
+# to import information about services offered by a site.
 #
 # The widget below contains information about the currently created service groups and a form
 # for uploading a new site file. Additional management of service information is provided by the
@@ -124,31 +82,40 @@
 from pdo.contracts.services import service_labels
 
 children = map(lambda stype : ServiceListWidget(state, bindings, stype), service_labels.keys())
-service_list = ipywidgets.Tab(children=list(children), titles=list(service_labels.values()))
+titles = service_labels.values()
+service_list = ipywidgets.Tab(children=list(children), titles=list(titles))
 ip_display.display(ipywidgets.VBox([service_list, ServiceUploadWidget(state, bindings)]))
 
 # %% [markdown]
-# ## Create Service Groups
+# ## Service Groups
 #
 # Service groups are a shortcut for configuration of collections of enclave, storage, and
 # provisioning services used to create and provision a PDO contract object. Each type of
 # service will have its own service groups. PDO requires that each type of service have a
 # service group named "default" that will be used when no groups have been specified.
 #
-# The widget below contains a list of service groups for each type of service and a widget for
-# creating new services of each type. If there is no default service group, please create one.
-#
 # Additional management of service group information is provided by the [Service Groups Manager
 # Notebook](service_groups_manager.ipynb)
 # %%
 from pdo.contracts.groups import ServiceGroupListWidget
 from pdo.contracts.groups import EnclaveServiceGroupCreateWidget
 from pdo.contracts.groups import ProvisioningServiceGroupCreateWidget
 from pdo.contracts.groups import StorageServiceGroupCreateWidget
-
+# %% [markdown]
+# ### List Service Groups
+#
+# The widget below contains a list of service groups for each type of service.
+# %%
 children = map(lambda stype : ServiceGroupListWidget(state, bindings, stype), service_labels.keys())
-ip_display.display(ipywidgets.Tab(children=list(children), titles=list(service_labels.values())))
+titles = service_labels.values()
+ip_display.display(ipywidgets.Tab(children=list(children), titles=list(titles)))
 
+# %% [markdown]
+# ### Create Service Groups
+#
+# The widget below enables creation of new service groups of each type. If there is no default
+# service group, please create one.
+# %%
 children = [
     EnclaveServiceGroupCreateWidget(state, bindings),
     ProvisioningServiceGroupCreateWidget(state, bindings),

docs/notebooks/documents/key_manager.py

@@ -14,7 +14,6 @@
 
 # %% [markdown]
 # # Key Management for PDO Contracts
-# ## WORK IN PROGRESS
 #
 # This notebook helps to manage keys for signing PDO contract transactions.
 

docs/notebooks/documents/service_manager.py

@@ -13,7 +13,7 @@
 # ---
 
 # %% [markdown]
-# # Service Management for PDO Contracts (WIP)
+# # Service Management for PDO Contracts
 #
 # This notebook helps to manage the services database.