Update dev instructions

CONTRIBUTING.md

@@ -1,56 +1,79 @@
-## Development install
+# Overview of AutoProfiler development
 
-Note: You will need NodeJS to build the extension package.
+AutoProfiler is a jupyter extension. It contains frontend typescript code and python code for executing pandas commands. These are bundled together into one jupyter extension that can be pip installed by a user.
 
-The `jlpm` command is JupyterLab's pinned version of
-[yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use
-`yarn` or `npm` in lieu of `jlpm` below.
+## Frontend Code
+
+The frontend svelte code is contained in the `src/` directory. We use the [svelte](https://learn.svelte.dev/tutorial/welcome-to-svelte) framework for components and do styling with [tailwind](https://tailwindcss.com/).
+
+-   [`index.ts`](src/index.ts) is the entrypoint for the extension that jupyter looks at to load the extension.
+-   The code roughly follows a Model, View, Controller pattern because that is how the jupyter extension examples are structured.
+    -   [`ProfilePanel.ts`](src/ProfilePanel.ts) -- main wrapper that creates a [`ProfileModel`](src/dataAPI/ProfileModel.ts) and [`ProfileView`](src/components/ProfileView.ts) and listens for changes to the notebook.
+    -   [`ProfileView`](src/components/ProfileView.ts) creates a [`Profiler.svelte`](src/components/Profiler.svelte) component that is the root component.
+    -   [`ProfileModel`](src/dataAPI/ProfileModel.ts) handles jupyter interactions to execute python code in the kernel and listen for changes to the notebook.
+
+## Python code
+
+The python code is contained in the `digautoprofiler/` directory. This is mostly utility functions that are called by the frontend code to execute pandas commands and return the results, along with automatically generated jupyter extension code in the `digautoprofiler/labextension` directory (don't manually edit this).
+
+# Development Setup and workflow
+
+To run AutoProfiler locally you need to install as a python library that is editable.
+
+## First time
+
+-   You will need [NodeJS and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) installed to build the extension package.
+-   It is best to make a new conda environment before following steps (e.g. `conda create --name autoprofiler python=3.11`)
+
+Then pip install the following:
 
-If first time, be sure to pip install the following:
 ```bash
 pip install jupyterlab jupyter-packaging
 ```
 
-Build steps:
+Now download and build extension:
+
 ```bash
-# Clone the repo to your local environment
-# Change directory to the AutoProfiler directory
+git clone https://github.com/cmudig/AutoProfiler.git
+cd AutoProfiler
 # Install package in development mode
 pip install -e .
 # Link your development version of the extension with JupyterLab
 jupyter labextension develop . --overwrite
-# Rebuild extension Typescript source after making changes
+# Build Typescript source after making changes
 npm run build
 ```
 
 Jupyter labextension can be weird sometimes; nuking the conda env and restarting tends to fix it.
 
-## Devloop: changes to js code in `src/`
+## Devloop: changes to frontend code in `src/`
 
 You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
 
+### Terminal 1
+
+Watch the source directory in one terminal, automatically rebuilding when changes are made to `src/`. You will need to refresh the browser to see changes.
+
 ```bash
-# Watch the source directory in one terminal, automatically rebuilding when needed
-jlpm watch
-# Run JupyterLab in another terminal
-jupyter lab
+cd AutoProfiler
+npm run watch
 ```
 
-**NOTE**: for some reason tailwind is not automatically re-loading classes during watch mode; if you add in new classes you will need to run `npm run build` to see changes.
-
-With the watch command running, every saved change will immediately be built locally and available in your running JupyterLab. Refresh JupyterLab to load the change in your browser (you may need to wait several seconds for the extension to be rebuilt).
+**Warning**: for some reason tailwind is not automatically re-loading classes during watch mode; if you add in new classes you will need to kill and restart the watch process or run `npm run build` to see changes.
 
-If you change the python code in `
+### Terminal 2
 
-By default, the `jlpm build` command generates the source maps for this extension to make it easier to debug using the browser dev tools. To also generate source maps for the JupyterLab core extensions, you can run the following command:
+To test your code you can run a jupyter lab instance in another terminal. **Note**: this does NOT have to be in the same directory (I would encourage you to have separate testing directory); as long as the conda environment is the same, any update to the `digautoprofiler` package will be reflected in the running jupyter lab instance.
 
 ```bash
-jupyter lab build --minimize=False
+cd /path/to/your/testing/directory
+conda activate autoprofiler
+jupyter lab
 ```
 
 ## Devloop: changes to python code in `digautoprofiler/`
-Changes to the python utility functions will update when the python module reupdates. If you restart the kernel, this should update the python package.
 
+Changes to the python utility functions will update when the python module reloads. If you restart the kernel in jupyter, this should update the python package (you don't even have to refresh the page, just kill and restart kernel).
 
 ## Development uninstall
 

TROUBLESHOOTING.md

@@ -12,7 +12,7 @@ pip install digautoprofiler
 
 ### Why isn't anything showing up?
 
-After pip installing, if you're not seeing AutoProfiler in the left side bar then the extension was not installed properly. Jupyter reads extensions from a directory wherever it is installed.
+After pip installing, if you're not seeing AutoProfiler in the side bar then the extension was not installed properly. Jupyter reads extensions from a directory wherever it is installed.
 
 Check 1: Run the command below in your terminal.