From 55cb144471155cb1edcc8e065576291d06616bf4 Mon Sep 17 00:00:00 2001 From: Andrew Maguire Date: Sun, 8 Jan 2023 00:47:14 +0000 Subject: [PATCH] dev --- notebooks/README.md | 6 +++++- notebooks/example/README.md | 41 +++++++++++++++++++++++++++++++++++-- 2 files changed, 44 insertions(+), 3 deletions(-) diff --git a/notebooks/README.md b/notebooks/README.md index edb5da33..fbe3a193 100644 --- a/notebooks/README.md +++ b/notebooks/README.md @@ -1,10 +1,14 @@ # Notebooks This is a folders with some useful notebooks, all the notebooks have a markdown -file with the same name explaining what they do. +file with the same name explaining what they do (or a README.md if its a single +notebook folder). ## Contributing Contributing to both notebooks and making new notebooks is very welcome. If you do so, make sure to make a markdown (.md) file to go with your notebook, makes it easier for people to know what your notebook is about. + +Check out the [example notebook](example/) for a reference example you can use +as a starting point. diff --git a/notebooks/example/README.md b/notebooks/example/README.md index f33af8fc..b975254a 100644 --- a/notebooks/example/README.md +++ b/notebooks/example/README.md @@ -1,6 +1,43 @@ # Example Notebook -[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/andrewm4894/Open-Assistant/blob/example-notebook/notebooks/example/example.ipynb) +[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/andrewm4894/Open-Assistant/blob/main/notebooks/example/example.ipynb) This folder contains an example reference notebook structure and approach for -this project. Please try and follow this structure as closely as possible. +this project. Please try and follow this structure as closely as possible. While +things will not exactly be the same for each notebook some principles we would +like to try ensure are: + +1. Each notebook or collection of related or dependant notebooks should live in + its own folder. +1. Each notebook should have a markdown file with the same name as the notebook + (or README.md if it's a single notebook folder) that explains what the + notebook does and how to use it. +1. Add an "Open in Colab" badge to the top of the notebook. +1. Make it as easy as possible for someone to run the notebook in Google Colab + or some other environment based on standard practices like providing a + `requirements.txt` file or anything else needed to successfully run the + notebook. + +## Running in Google Colab + +At the top of the notebook there is a code cell that will (once uncommented): + +1. clone the repository into your colab instance. +1. `cd` into the relevant notebook directory. +1. run `pip install -r requirements.txt` to install the required packages. + +At this point you can run the notebook as normal and the folder structure will +match that of the repository and the colab notebook will be running from the +same directory that the notebook lives in so relative links etc should work as +expected (for example `example.ipynb` will read some sample data from +`data/data.csv`). + +If you are adding a notebook please try and add a similar cell to the top of the +notebook so that it is easy for others to run the notebook in colab. + +## example.ipynb + +This notebook contains an example "Open In Colab" badge and a code cell to +prepare the colab environment to run the notebook. It also contains a code cell +that will read in some sample data from the `data` folder in the repository and +display it as a pandas dataframe.