Migrate CONTRIBUTING to nbdev generated READEME

Jupyter4Science · Mar 27, 2024 · f4b6eb4 · f4b6eb4
1 parent b408a78
commit f4b6eb4
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 96 deletions.
diff --git a/CONTRIBUTING b/CONTRIBUTING
diff --git a/README.md b/README.md
@@ -2,21 +2,59 @@
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
-This file will become your README and also the index of your
-documentation.
+## Developing locally with conda
 
-## Install
+Assuming you have
+[conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html)
+installed…
+
+1.  Create a new environment using version 3.11 of python with the
+    following command:
 
 ``` sh
-pip install jupyter_mentor
+conda create -f environment.yml
 ```
 
-## How to use
+2.  Go to the directory of your cloned repository and activate your
+    envrionment:
+
+``` sh
+conda activate jupyter-mentor
+```
 
-Fill me in please! Don’t forget code examples:
+3.  Open the JupyterLab editor:
 
-``` python
-1+1
+``` sh
+cd path/to/your/cloned/repo
+jupyter lab
 ```
 
-    2
+## Developing with Docker
+
+WARNING! Development with Docker is not recommended at this time.
+However, GitHub actions runs repo2docker to verify that this repository
+is compatible with Binder.
+
+### Developing on MacOS
+
+1.  Install Docker with `brew install --cask docker`. If this command
+    does not work, you may need to [install Homebrew](https://brew.sh/)
+2.  Start Docker by clicking on application icon or by running
+    `open -a Docker`
+3.  Pull the docker image from DockerHub to you local machine using
+    `docker image pull brewer36/jupyter-mentor:macos`
+4.  `cd <location_of_your_clone>`
+5.  Launch JupyterLab with
+    `docker run -it --rm -p 8888:8888 brewer36/jupyter-mentor:macos jupyter lab --ip=0.0.0.0 --port=8888`
+
+### Updating brewer36/jupyter-mentor:latest (linux) image with GitHub acitons
+
+No extra steps required. This GitHub action automatically updates the
+image with each new commit.
+
+### Updating brewer36/jupyter-mentor:macos (arm64 for M1 chip) image with repo2docker
+
+1.  Install repo2docker with
+    `python3 -m pip install jupyter-repo2docker`
+2.  `cd <location_of_your_clone>`
+3.  `repo2docker --Repo2Docker.platform=linux/arm64 --image-name=brewer36/jupyter-mentor:macos ./`
diff --git a/nbs/index.ipynb b/nbs/index.ipynb
@@ -23,57 +23,48 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This file will become your README and also the index of your documentation."
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Install"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "```sh\n",
-    "pip install jupyter_mentor\n",
+    "## Developing locally with conda\n",
+    "\n",
+    "Assuming you have [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) installed...\n",
+    "\n",
+    "1. Create a new environment using version 3.11 of python with the following command: \n",
+    "``` sh\n",
+    "conda create -f environment.yml\n",
+    "```\n",
+    "2. Go to the directory of your cloned repository and activate your envrionment:\n",
+    "``` sh\n",
+    "conda activate jupyter-mentor\n",
+    "```\n",
+    "3. Open the JupyterLab editor: \n",
+    "``` sh\n",
+    "cd path/to/your/cloned/repo\n",
+    "jupyter lab\n",
     "```"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## How to use"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "Fill me in please! Don't forget code examples:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "2"
-      ]
-     },
-     "execution_count": null,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "1+1"
+    "## Developing with Docker\n",
+    "\n",
+    "WARNING! Development with Docker is not recommended at this time. However, GitHub actions runs repo2docker to verify that this repository is compatible with Binder.\n",
+    "\n",
+    "### Developing on MacOS\n",
+    "\n",
+    "1. Install Docker with `brew install --cask docker`. If this command does not work, you may need to [install Homebrew](https://brew.sh/)\n",
+    "2. Start Docker by clicking on application icon or by running `open -a Docker`\n",
+    "3. Pull the docker image from DockerHub to you local machine using `docker image pull brewer36/jupyter-mentor:macos`\n",
+    "4. `cd <location_of_your_clone>` \n",
+    "5. Launch JupyterLab with `docker run -it --rm -p 8888:8888 brewer36/jupyter-mentor:macos jupyter lab --ip=0.0.0.0 --port=8888`\n",
+    "\n",
+    "### Updating brewer36/jupyter-mentor:latest (linux) image with GitHub acitons\n",
+    "No extra steps required. This GitHub action automatically updates the image with each new commit.\n",
+    "\n",
+    "### Updating brewer36/jupyter-mentor:macos (arm64 for M1 chip) image with repo2docker\n",
+    "1. Install repo2docker with `python3 -m pip install jupyter-repo2docker`\n",
+    "2. `cd <location_of_your_clone>` \n",
+    "3. `repo2docker --Repo2Docker.platform=linux/arm64 --image-name=brewer36/jupyter-mentor:macos ./` "
    ]
   },
   {