Update documentation

contributor_guide/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: b16c3cb86fad2c448e380ad3fd492aa5
+tags: 645f666f9bcd5a90fca523b33c5a78b7

contributor_guide/_sources/contributor_guide/contribute/chapter1.ipynb

@@ -0,0 +1,49 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c20bffe2-d852-4b42-9c80-e43dbe8ebc45",
+   "metadata": {},
+   "source": [
+    "# Request to Join as a Contributor"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5942212f-37f3-418e-b3cb-d852552e32cc",
+   "metadata": {},
+   "source": [
+    "In order to start contributing to OPE, you will need to first request to join the [OPEFFORT organization](https://github.com/OPEFFORT) on GitHub. Once your request is accepted you will be able to start contributing."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7be097d8-e9a2-4491-9e9e-ccf456698754",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

contributor_guide/_sources/contributor_guide/contribute/chapter2.ipynb

@@ -0,0 +1,129 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c20bffe2-d852-4b42-9c80-e43dbe8ebc45",
+   "metadata": {},
+   "source": [
+    "# Set Up"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5942212f-37f3-418e-b3cb-d852552e32cc",
+   "metadata": {},
+   "source": [
+    "You will want to create your own forked repository from one of the [ope repositories](https://github.com/OPEFFORT). The main development repository is the [ope-project](https://github.com/OPEFFORT/ope-project) repo. You can then make changes within your own forked repo and then open a pull reuqest to the associated OPEFFORT repo. \n",
+    "```{note}\n",
+    "There are three important folders that you will use in the ope-project repo: /containers, /content, /books. The containers folder will hold all of the configurations and the Dockerfile for your docker image. The content folder will hold all of the .ipynb files plus additional files used to structure your book. The books folder contains the makefile to build and publish your book from the content folder.\n",
+    "```\n",
+    "\n",
+    "## The Development Environment\n",
+    "\n",
+    "The OPE project utilizes python3 as the main language. The environment is centered around the utilization of the `jupyter-book` package. We also utilize [Docker](https://docs.docker.com/engine/install/) in order to build and deploy the containers. [Make](https://www.gnu.org/software/make/) is used to automate the building of the project. The containers are currently being deployed onto the [New England Research Cloud](https://nerc.mghpcc.org/) (NERC) using [OpenShift](https://www.redhat.com/en/technologies/cloud-computing/openshift) and [Red Hat OpenShift Data Science](https://www.redhat.com/en/technologies/cloud-computing/openshift/openshift-data-science) (RHODS).\n",
+    "\n",
+    "### Installation and Setup\n",
+    "\n",
+    "It is recommended to first setup a virtual environment to install the necessary packages to. In order to set the virtual environment up you must first have [python3](https://www.python.org/downloads/) installed on your system. Once that is done, open a terminal within the development repository and do the following to setup the virtual environment:\n",
+    "\n",
+    "```shell\n",
+    "mkdir .venv/ ; python3 -m venv .venv/\n",
+    "```\n",
+    "\n",
+    "Execute the following command in the same directory as the .venv/ directory in order to activate the virtual environment\n",
+    "```shell\n",
+    "source .venv/bin/activate\n",
+    "```\n",
+    "\n",
+    "The virtual environment can be deactivated by executing the following command\n",
+    "```shell\n",
+    "deactivate\n",
+    "```\n",
+    "\n",
+    "Once the virtual environment has been activated, use pip to install the following packages:\n",
+    "\n",
+    "```shell\n",
+    "pip install jupyter-book\n",
+    "```\n",
+    "```shell\n",
+    "pip install ghp-import\n",
+    "```\n",
+    "\n",
+    "\n",
+    "## Creating a New Project\n",
+    "\n",
+    "Please refer to the [\"Creating a New Project\"](https://isaiahstapleton.github.io/ope-project/user_guide/project/chapter1.html) section of the OPE user guide.\n",
+    "\n",
+    "## Creating a New Book\n",
+    "\n",
+    "Please refer to the [\"Creating a New Book\"](https://isaiahstapleton.github.io/ope-project/user_guide/book/chapter1.html) section of the OPE user guide.\n",
+    "\n",
+    "## Customizing Image\n",
+    "\n",
+    "Every new project that is created contains the base container image located within containers/default in the project repo. Navigate to the containers/default directory and run make build in order to build this base image. The base image typically takes ~15 mins to build.\n",
+    "\n",
+    "In order to customize the base image, navigate to containers/default/base and make changes to the following files as needed:\n",
+    "\n",
+    "- **python_prereqs:** Python packages that will be installed right before installing the main python packages, specified in the file right below this.\n",
+    "\n",
+    "- **python_pkgs:** Python packages that will be installed.\n",
+    "\n",
+    "- **distro_pkgs:** Linux distro packages that will be installed.\n",
+    "\n",
+    "- **Dockerfile:** The base OPE image is created in a way such that you can modify the configuration files above in order to install the necessary software within the container. However, you may need to modify the Dockerfile in order to fit more specific needs.\n",
+    "\n",
+    "Make sure to also make changes to these following files in order to get your image tagged correctly and to ensure it gets pushed to the correct container registry repository:\n",
+    "\n",
+    "- **customization_name:** Image tag name \n",
+    "\n",
+    "- **ope_book_registry:** The name of the container registry site\n",
+    "\n",
+    "- **ope_book_user:** The username for the account where the repository is located on the container registry site\n",
+    "\n",
+    "- **ope_book:** The name of the repository on the container registry user account\n",
+    "\n",
+    "```{note}\n",
+    "ope_book_registry/ope_book_user/ope_book defines the url for the repository within the container registry site. For example, quay.io/opeffort/ope_book.\n",
+    "```\n",
+    "\n",
+    "```{warning}\n",
+    "You will need to have the Docker daemon running in the background to build your image.\n",
+    "```\n",
+    "\n",
+    "### Startup Script\n",
+    "\n",
+    "A [startup script](https://github.com/OPEFFORT/ope-project/blob/main/containers/default/base/start-notebook.d/ope-sartup.sh) is executed during image building (specified at the end of the Dockerfile). This startup script is responsible for mounting the home directory in order to achieve permanent storage. If this script is not executed and the home directory is not mounted, the home directory within the resulting container is deleted when the container is stopped. The script needs to be executed as the jovyan user during image building in order to have the correct permission to mount the home directory toa  permanent storage. \n",
+    "\n",
+    "\n",
+    "### UID/GID \n",
+    "\n",
+    "When developing on the NERC test cluster, the ope_uid value is set to be 1000810000 in order to match the NERC environment. For the BU-ROSA cluster, it may assign containers with different UID/GID, so we have to customize the [ope_uid](https://github.com/OPEFFORT/ope-project/blob/main/containers/default/base/ope_uid) and [ope_gid](https://github.com/OPEFFORT/ope-project/blob/main/containers/default/base/ope_gid) value to match that environment. These values can be changed accordingly for the necessary environment. \n",
+    "\n",
+    "## Running Container Locally\n",
+    "\n",
+    "After the image has been built, it may be run locally using `make`. Navigate to the directory that has the name of the image you are trying to run (ex. containers/default). Once you are in this directory with the `Makefile`, run `Make root` in order to execute the locally built image as a container. Refer to section 10, [Building and Publishing Image](https://isaiahstapleton.github.io/ope-project/user_guide/container/chapter2.html) of the user guide for more information.\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

contributor_guide/_sources/contributor_guide/contribute/chapter3.ipynb

@@ -0,0 +1,110 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c20bffe2-d852-4b42-9c80-e43dbe8ebc45",
+   "metadata": {},
+   "source": [
+    "# CI/CD Testing Workflow"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5942212f-37f3-418e-b3cb-d852552e32cc",
+   "metadata": {},
+   "source": [
+    "The base ope image is currently located within the `OPE-Testing` repo in the `container-base-ope` repo. Within this repository there is a `Master_Container_Test.yaml` file in the .github/workflows directory. This yaml file contains all the appropriate image, build, gdb and UI tests compressed into one for the OPE repository base container image. Whenever there is code pushed to this branch the GitHub workflow will activate in order to test the container to make sure it is still fully functional.\n",
+    "\n",
+    "There are currently 11 stages to the workflow listed below:\n",
+    "\n",
+    "## Setup-and-Build\n",
+    "\n",
+    "Responsible for building the image, pushing the beta image to the registry of quay.io, and recording the time and size of the build. All other jobs wait for this to complete before beginning.\n",
+    "\n",
+    "\n",
+    "## Health-Check\n",
+    "\n",
+    "Test pulls the beta image and runs it, after some time executes  a health status check to veridy if the container is up and running.\n",
+    "\n",
+    "\n",
+    "## Image-Version-Check\n",
+    "\n",
+    "Test pulls the beta image and runs it, then queries the image json to ensure the proper image and tag are used.\n",
+    "\n",
+    "\n",
+    "## JupyterNB-Test\n",
+    "\n",
+    "Test pulls the beta image and runs it. Starts up jupyter lab server in the container and then runs test.ipynb which verfies import of necessary packages. If error does not occur when executing notebook, behaving as expected.\n",
+    "\n",
+    "\n",
+    "## Package-Version-Test\n",
+    "\n",
+    "Test pulls the beta image and runs it. Checks what version of packages are installed within the running container and then passes that to version_check.py to compare the current list with a stable list (versions.txt) and finds any inconsistencies.\n",
+    "\n",
+    "\n",
+    "## Checksum\n",
+    "\n",
+    "Checksum verifies that the checksum of the container image is correct.\n",
+    "\n",
+    "\n",
+    "## Size-and-Time-Display\n",
+    "\n",
+    "Test pulls the beta image and runs it (needed for size)This test uses the build time recorded in the build to display this time and also queries the image to find its size and display that. \n",
+    "\n",
+    "\n",
+    "## UI-Test\n",
+    "\n",
+    "This test infrastructure uses selenium to run functionality and visual checks on jupyter notebook running in the image. It pulls the beta image and runs it. Then, the url is passed to rise_test.py which is then used to do the functionality testing with selenium and record screenshots for the visual / formatting veriication test. After this, the screenshot difference test is triggered which runs screenshots_diff.py for final format checking.\n",
+    "\n",
+    "\n",
+    "## GDB-Test\n",
+    "\n",
+    "Test pulls the beta image and runs it. It then runs a bash sript calling gdb 100 times to check functionality. If gdb error will throw here. Lastly, rights the output of the script to text file that then verifies the corrrect number of instructions have been executed.\n",
+    "\n",
+    "\n",
+    "## Approval\n",
+    "\n",
+    "Sends approval authorization request to approved authorization, test then waits for authorization has been granted to proceed. \n",
+    "\n",
+    "\n",
+    "## Publish\n",
+    "\n",
+    "This test publishes the latest stable base image to the OPE quay.io repo\n",
+    "\n",
+    "\n",
+    "```{note}\n",
+    "In order to push / pull to the appropriate quay.io repo you must update registry_user and registry_password to the correct corresponding variables\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7be097d8-e9a2-4491-9e9e-ccf456698754",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

contributor_guide/_sources/contributor_guide/intro/chapter1.ipynb

@@ -0,0 +1,69 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "c20bffe2-d852-4b42-9c80-e43dbe8ebc45",
+   "metadata": {},
+   "source": [
+    "# What is the goal of OPE?"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5942212f-37f3-418e-b3cb-d852552e32cc",
+   "metadata": {},
+   "source": [
+    "## Increasing Accessiblity in Computer Science Education\n",
+    "\n",
+    "The goal of OPE is that all materials, Textbook, Lecture presentations, and Lab manual are developed in open formats, hosted in public repositories, and deployed in a live and interactive manner and that the only thing require access to a web browser.\n",
+    "\n",
+    "## Creating Standard for Open Source Textbooks\n",
+    "\n",
+    "Creating a standard, streamlined way for educators to create Open Source Textbooks will have numerous benefits:\n",
+    "\n",
+    "1. It will increase accessibility with Computer Science education by allowing anyone, no matter their background, to easily setup and interact with an environment tailored towards educating individuals on Computer Science principles.\n",
+    "\n",
+    "2. It will allow educators to easily create textbook content that is specifically tailored to their course needs, in an simple, streamlined manner.\n",
+    "\n",
+    "## Creating Associated Container Images\n",
+    "\n",
+    "Creating container images that are directly associated with the textbook has numerous benefits:\n",
+    "\n",
+    "1. It requires that students/learners only need to have access to a web browser in order to interact with the class/book activities.\n",
+    "\n",
+    "2. The required environment is automatically setup for the students/learners, decreasing amount of time it takes to setup the environment. Students/learners do not need to setup the required environment manually by themselves.\n",
+    "\n",
+    "3. It creates a uniform environment for all students/learners. Every student/learner that builds the image has access to the exact same software and packages, with the same versions. This eliminates the opportunity for issues to arise with students/learners when working with different versions of software.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7be097d8-e9a2-4491-9e9e-ccf456698754",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

contributor_guide/_sources/contributor_guide/intro/chapter2.ipynb

@@ -0,0 +1,29 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# OPE Architecture "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There is a collection of repositories hosted in the [Github OPEFFORT Organization](https://github.com/OPEFFORT). \n",
+    "\n",
+    "<img src=\"../../images/OPE-Architecture.png\" width=100%> \n",
+    "\n"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  },
+  "orig_nbformat": 4
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}