Clean up high level documentation

General clean up of the install and jupyter documentation that is
generally intended to be read outside of the notebook interface.

Signed-off-by: Mic Bowman <mic.bowman@intel.com>

docs/install.md

@@ -78,17 +78,19 @@ virtual environment in the directory `${PDO_INSTALL_ROOT}`.
 make -C ${PDO_SOURCE_ROOT}/build client
 ```
 
-Finally, activate the PDO Python virtual environment:
-
-```
-source ${PDO_INSTALL_ROOT}/bin/activate
-```
-
 More information about PDO client installation is found in the
 [PDO documentation](../private-data-objects/docs/client_install.md).
 
 ## <a name="contracts">Build and Install the PDO Contracts Packages</a>
 
+Activate the PDO Python virtual environment and install the
+Python packages necessary to build contracts:
+
+```bash
+source ${PDO_INSTALL_ROOT}/bin/activate
+${PDO_INSTALL_ROOT}/bin/pip install jupytext
+```
+
 Finally, build and install the Python packages associated with the PDO contract
 families. The packages will be built in the directory
 `${PDO_CONTRACTS_ROOT}/build/dist`.
@@ -104,3 +106,10 @@ on ${SERVICE_HOST}, you can test the installation with the following:
 ```
 TEST_SERVICE_HOST=${SERVICE_HOST} make -C ${PDO_CONTRACTS_ROOT} test
 ```
+
+If you wish to use [Jupyter notebooks](jupyter.md) to interact with
+PDO contracts, you will need to install several additional packages:
+
+```bash
+${PDO_INSTALL_ROOT}/bin/pip install jupyterlab papermill ipywidgets
+```

docs/jupyter.md

@@ -3,35 +3,35 @@ Licensed under Creative Commons Attribution 4.0 International License
 https://creativecommons.org/licenses/by/4.0/
 --->
 
-# Using Jupyter Labs for Exchange Contracts #
+# Using Jupyter Labs for PDO Contracts #
 
 This directory contains several sample Jupyter notebooks that can be
 used to create and interact with contract objects (or collections of
-objects) in the Exchange contract family.
+objects).
 
 ## Installation ##
 
 There are many places to find information about [installation of
 Jupyter](https://jupyter.org/install). Please consult one of the very
 good guides for a complete installation and configuration.
 
-A basic installation of Jupyter notebook is relatively easy assuming
+A basic installation of Jupyter Labs is relatively easy assuming
 that you have successfully installed the PDO client in a Python
-virutal environment and that the Exchange contract family has been installed.
+virutal environment and that the PDO contracts have been installed.
 
 * Activate the virtual environment: `source $PDO_INSTALL_ROOT/bin/activate`
-* Install the Jupyter notebook package: `pip install notebook`
+* Install the Jupyter Labs package: `pip install jupyterlab`
 * Install [Papermill](https://papermill.readthedocs.io/en/latest/): `pip install papermill`
 * Install [Jupytext](https://jupytext.readthedocs.io/en/latest/): `pip install jupytext`
 * Install [IPYWidgets](https://ipywidgets.readthedocs.io/en/stable/): `pip install ipywidgets`
 
-Note that you will need to reinstall Jupyter and papermill any time
+Note that you will need to reinstall these packages anytime
 you rebuild the Python virtual environment.
 
-## Running Jupyter Notebook Server ##
+## Running Jupyter Labs Server ##
 
 Please consult the Jupyter documentation for information about
-configuration of the Jupyter server.
+configuration of the Jupyter Labs server.
 
 Notebook files will automatically be installed to the directory
 `${PDO_HOME}/notebooks`.  The files may be copied to another directory
@@ -59,45 +59,6 @@ cd ${PDO_JUPYTER_ROOT}
 jupyter lab --no-browser --port=8888
 ```
 
-## Structure of a Notebook ##
-
-The templates provided generally share five common sections:
-
-* Configure the Contract Object
-* Initialize the Interpreter and the PDO Environment
-* Initialize the Contract Object Context
-* Operate on the Contract
-* View Contract Metadata
-
-To initialize the interpreter, the notebook loads the Juptyer
-helper module. This module imports all of the relevant PDO and
-Exchange modules to simplify access for code in the notebook. It also
-defines several procedures that are useful for initializing and
-interacting with the environment.
-
-In addition, the 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.
-
-The next section in the notebook configures information about the
-contract object associated with the notebook. In some cases, the
-variables will set by the notebook using the Papermill extensions. In
-some cases, the variables may be customized for the specific behavior
-desired.
-
-The following section initializes the PDO environment from the PDO
-configuration files. There may be opportunities for customization, but
-so long as the PDO configuration is complete changes to this section
-should be infrequent.
-
-The final common section initializes the contract context. Where the
-PDO initialization handles configuration of the PDO modules, this
-section handles configuration of the specific contract object and its
-relationship to other contract objects.
-
 ## Getting Started
 
 The easiest way to get started is to use the Jupyter file browser to

docs/notebooks/.gitignore

@@ -0,0 +1 @@
+*.ipynb