Skip to content

Commit 3db8ef9

Browse files
committed
docs(setup)📝: streamline and simplify setup instructions for running notebooks
- Replace multiple setup options (Binder, VSCode dev containers, conda, venv) with a single, quick setup guide using uv and marimo. - Provide clear, step-by-step instructions for installing uv, navigating to the notebook directory, and running notebooks with marimo. - Explain the benefits of the new approach, including isolated environments and automatic dependency management. - Remove outdated or redundant setup instructions to reduce confusion and improve onboarding experience.
1 parent dd7f8c7 commit 3db8ef9

File tree

1 file changed

+20
-106
lines changed

1 file changed

+20
-106
lines changed

‎notebooks/00-preface/01-setup.md‎

Lines changed: 20 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -4,118 +4,32 @@ In order to get the most of this book,
44
you will want to be able to execute the examples in the notebooks,
55
modify them, break the code, and fix it.
66
Pedagogically, that is the best way for you to learn the concepts.
7-
Here are the recommended ways in which you can get set up.
7+
Here's the recommended way to get set up.
88

9-
## Binder
9+
## Quick Setup
1010

11-
We recommend the use of Binder!
12-
This is because Binder will automagically setup
13-
an isolated and ephemeral compute environment for you
14-
with all of the packages needed to run the code in your notebooks.
15-
As such, you won't have to wrestle with anything at the terminal.
16-
To go there, click on the following button:
11+
To get started with the notebooks, follow these simple steps:
1712

18-
[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/ericmjl/Network-Analysis-Made-Simple/master)
13+
1. **Install uv** (the Python package manager):
14+
Follow the installation instructions at [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)
1915

20-
## VSCode Development Containers
16+
2. **Navigate to the notebook directory**:
17+
```bash
18+
cd notebooks/subdir/
19+
```
2120

22-
Assuming that y ou're using Visual Studio Code
23-
and have attempted to use development containers before,
24-
you can run the Network Analysis Made Simple tutorial content
25-
inside a development container.
26-
After Binder, this is the second easiest way to get set up.
27-
You need to have Docker installed on your computer
28-
but don't worry -- you won't have to execute any Docker commands :).
21+
3. **Run the notebook**:
22+
```bash
23+
uvx marimo edit --sandbox <notebook_name>.py
24+
```
2925

30-
### Install the Remote Containers extension
26+
That's it! The `--sandbox` flag ensures a clean, isolated environment for running the notebooks with all necessary dependencies automatically managed.
3127

32-
This is found in the Extensions marketplace.
28+
## What this does
3329

34-
![Remote Containers extension.](https://user-images.githubusercontent.com/2631566/164070556-7ca675bc-d700-4e1b-a8e4-f07bc77c79f8.png)
30+
- **uv** is a fast Python package manager that handles dependency resolution and virtual environments
31+
- **marimo** is an interactive notebook environment optimized for Python
32+
- The `--sandbox` flag creates an isolated environment for each notebook, preventing dependency conflicts
33+
- All required packages are automatically installed when you run the notebook
3534

36-
### Clone the repository to your local drive
37-
38-
```bash
39-
git clone https://github.com/ericmjl/Network-Analysis-Made-Simple.git
40-
```
41-
42-
### Open the repository in VSCode
43-
44-
Use `Cmd+Shift+P` (on macOS) or `Ctrl+Shift+P` (on Linux/Windows)
45-
to open the command palette, and search for "Rebuild and Reopen in Container" as below:
46-
47-
![Search for "Rebuild and Reopen in Container"](https://user-images.githubusercontent.com/2631566/164071398-ff115bd0-02fc-4827-935a-2785a354360f.png)
48-
49-
Hit enter and wait for the container to build automagically. This may take around 10 minutes or so, depending on your system.
50-
51-
![Development container will be built.](https://user-images.githubusercontent.com/2631566/164071594-d3ddf3fa-9c78-48f3-be56-09a453f8eb0a.png)
52-
53-
## `conda` environments
54-
55-
We also recommend the use of `conda` environments!
56-
Use this if you're not already using one of the options above.
57-
If you are feeling confident enough to set up
58-
a conda environment at the terminal,
59-
then follow along.
60-
(We'll be assuming you've already cloned the repository locally.)
61-
62-
### Leverage the Makefile
63-
64-
We've provided a Makefile with a single command:
65-
66-
```bash
67-
make conda
68-
```
69-
70-
On most \*nix systems, that should get you most of the way
71-
to having the environment setup.
72-
73-
### Alternative: Execute individual commands
74-
75-
If you encounter errors, then you should know that the Makefile command
76-
`make conda`
77-
basically wraps the following steps.
78-
79-
Firstly, it creates the conda environment based on the `environment.yml` file:
80-
81-
```bash
82-
conda env create -f environment.yml
83-
```
84-
85-
Next, it activates the environment:
86-
87-
```bash
88-
conda activate nams
89-
```
90-
91-
We have a custom module for the project, which is called `nams`,
92-
that you will have to install.
93-
94-
```bash
95-
# In the root directory of the cloned repository
96-
python setup.py develop
97-
```
98-
99-
Finally, it runs a check on the environment
100-
to make sure everything is installed correctly:
101-
102-
```bash
103-
python checkenv.py
104-
```
105-
106-
## `venv` environments
107-
108-
If you're not a `conda` user, then you can use `venv` to create your environment.
109-
110-
111-
### Leverage the Makefile
112-
113-
As with the `conda` commands, you should be able
114-
to execute a single Makefile command at your terminal:
115-
116-
```bash
117-
make venv
118-
```
119-
120-
Special heartfelt thanks goes out to GitHub user @matt-land
121-
who contributed the `venv` script.
35+
This approach eliminates the need for manual environment setup, conda environments, or Docker containers while ensuring reproducible execution of the tutorial content.

0 commit comments

Comments
 (0)