From a6819a6fc564d8455c546c320e29d8793b0affa5 Mon Sep 17 00:00:00 2001 From: Mic Bowman Date: Thu, 4 Apr 2024 12:39:55 -0600 Subject: [PATCH] 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 --- docs/install.md | 21 ++++++++++----- docs/jupyter.md | 55 ++++++--------------------------------- docs/notebooks/.gitignore | 1 + 3 files changed, 24 insertions(+), 53 deletions(-) create mode 100644 docs/notebooks/.gitignore diff --git a/docs/install.md b/docs/install.md index 49d2d13..3557b94 100644 --- a/docs/install.md +++ b/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). ## Build and Install the PDO Contracts Packages +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 +``` diff --git a/docs/jupyter.md b/docs/jupyter.md index ecb54ec..c12dc1e 100644 --- a/docs/jupyter.md +++ b/docs/jupyter.md @@ -3,11 +3,11 @@ 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 ## @@ -15,23 +15,23 @@ 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 diff --git a/docs/notebooks/.gitignore b/docs/notebooks/.gitignore new file mode 100644 index 0000000..fa65608 --- /dev/null +++ b/docs/notebooks/.gitignore @@ -0,0 +1 @@ +*.ipynb