consolidate venv docs (#1468)

Author: mbostock

docs/loaders.md

@@ -161,12 +161,20 @@ For example, for the file `quakes.csv`, the following data loaders are considere
 
 To use an interpreted data loader (anything other than `.exe`), the corresponding interpreter must be installed and available on your `$PATH`. Any additional modules, packages, libraries, _etc._, must also be installed. Some interpreters are not available on all platforms; for example `sh` is only available on Unix-like systems.
 
-<div class="tip">
+<div class="tip" id="venv">
 
-You can use a virtual environment in Python, such as [uv](https://github.com/astral-sh/uv), to install libraries locally to the project. This is useful when working in multiple projects, and when collaborating; you can also track dependencies in a `requirements.txt` file. To create a virtual environment with uv, run:
+You can use a virtual environment in Python, such as [venv](https://docs.python.org/3/tutorial/venv.html) or  [uv](https://github.com/astral-sh/uv), to install libraries locally to the project. This is useful when working in multiple projects, and when collaborating; you can also track dependencies in a `requirements.txt` file.
+
+To create a virtual environment with venv:
+
+```sh
+python3 -m venv .venv
+```
+
+Or with uv:
 
 ```sh
-uv venv # Create a virtual environment at .venv.
+uv venv
 ```
 
 To activate the virtual environment on macOS or Linux:
@@ -181,7 +189,7 @@ Or on Windows:
 .venv\Scripts\activate
 ```
 
-You can then run the `observable preview` or `observable build` commands as usual; data loaders will run within the virtual environment. Run the `deactivate` command to exit the virtual environment.
+You can then run the `observable preview` or `observable build` (or `npm run dev` or `npm run build`) commands as usual; data loaders will run within the virtual environment. Run the `deactivate` command or use Control-D to exit the virtual environment.
 
 </div>
 

examples/loader-python-to-csv/src/index.md

@@ -28,22 +28,15 @@ results.to_csv(sys.stdout)
 
 <div class="note">
 
-To run this data loader, you’ll need python3 and the geopandas, matplotlib, io, and sys modules installed and available on your `$PATH`. We recommend setting up a virtual environment.
+To run this data loader, you’ll need python3 and the geopandas, matplotlib, io, and sys modules installed and available on your `$PATH`.
 
 </div>
 
-To start and activate a virtual Python environment, run the following commands:
+<div class="tip">
 
-```
-$ python3 -m venv .venv
-$ source .venv/bin/activate
-```
-
-Then install the required modules from `requirements.txt` using:
+We recommend using a [Python virtual environment](https://observablehq.com/framework/loaders#venv), such as with venv or uv, and managing required packages via `requirements.txt` rather than installing them globally.
 
-```
-$ pip install -r requirements.txt
-```
+</div>
 
 The above data loader lives in `data/predictions.csv.py`, so we can load the data using `data/predictions.csv` with `FileAttachment`:
 

examples/loader-python-to-png/src/index.md

@@ -26,14 +26,13 @@ sys.stdout.buffer.write(img_buffer.getvalue())
 
 <div class="note">
 
-To run this data loader, you’ll need python3 and the geopandas, matplotlib, io, and sys modules installed and available on your `$PATH`. We recommend setting up a virtual environment, _e.g._ with:
+To run this data loader, you’ll need python3 and the geopandas, matplotlib, io, and sys modules installed and available on your `$PATH`.
 
-- `$ python3 -m venv .venv`
-- `$ source .venv/bin/activate`
+</div>
 
-Then install the required modules:
+<div class="tip">
 
-- `$ pip install -r requirements.txt`
+We recommend using a [Python virtual environment](https://observablehq.com/framework/loaders#venv), such as with venv or uv, and managing required packages via `requirements.txt` rather than installing them globally.
 
 </div>
 

examples/loader-python-to-zip/src/data/earthquakes.zip.py

@@ -31,7 +31,7 @@
 
 # Write JSON string to the zip file
 with zipfile.ZipFile(zip_buffer, "w") as zip_file:
-    zip_file.writestr("quakes_metadata.json", earthquake_meta_json)
+    zip_file.writestr("quakes-metadata.json", earthquake_meta_json)
 
 # Write DataFrame to a CSV file in the zip file
 with zipfile.ZipFile(zip_buffer, "a") as zip_file:

examples/loader-python-to-zip/src/index.md

@@ -36,7 +36,7 @@ zip_buffer = io.BytesIO()
 
 # Write JSON string to the zip file
 with zipfile.ZipFile(zip_buffer, "w") as zip_file:
-    zip_file.writestr("quakes_metadata.json", earthquake_meta_json)
+    zip_file.writestr("quakes-metadata.json", earthquake_meta_json)
 
 # Write DataFrame to a CSV file in the zip file
 with zipfile.ZipFile(zip_buffer, "a") as zip_file:
@@ -49,45 +49,40 @@ sys.stdout.buffer.write(zip_buffer.getvalue())
 
 <div class="note">
 
-To run this data loader, you’ll need python3, and the requests and pandas modules, installed and available on your `$PATH` (json, zipfile, io, and sys are part of the python3 standard library). We recommend setting up a virtual environment, for example using:
+To run this data loader, you’ll need python3, and the requests and pandas modules, installed and available on your `$PATH`. (json, zipfile, io, and sys are part of the python3 standard library.)
 
-- `$ python3 -m venv .venv`
-- `$ source .venv/bin/activate`
+</div>
 
-Install the requests and pandas modules (included in requirements.txt):
+<div class="tip">
 
-- `$ pip install -r requirements.txt`
+We recommend using a [Python virtual environment](https://observablehq.com/framework/loaders#venv), such as with venv or uv, and managing required packages via `requirements.txt` rather than installing them globally.
 
 </div>
 
-The above data loader lives in `data/earthquakes.zip.py`. You can load the entire ZIP archive in a markdown page using FileAttachment:
+The above data loader lives in `data/earthquakes.zip.py`. You can load the entire ZIP archive in a markdown page using `FileAttachment`:
 
 ```js echo
-const quakeZip = FileAttachment("data/earthquakes.zip").zip()
+const earthquakes = FileAttachment("data/earthquakes.zip").zip();
 ```
 
-Or access individual files (`quakes_metadata.json` and `quakes.csv`) directly:
+Or access individual files (`quakes-metadata.json` and `quakes.csv`) directly:
 
 ```js echo
-const quakeMetadata = FileAttachment("data/earthquakes/quakes_metadata.json").json()
+const quakesMetadata = FileAttachment("data/earthquakes/quakes-metadata.json").json();
 ```
 
 ```js echo
-const quakeData = FileAttachment("data/earthquakes/quakes.csv").csv({typed: true})
+const quakes = FileAttachment("data/earthquakes/quakes.csv").csv({typed: true});
 ```
 
-Take a quick look at the quakes data using Inputs.table:
+Take a quick look at the quakes data using `Inputs.table`:
 
 ```js echo
-Inputs.table(quakeData)
+Inputs.table(quakes)
 ```
 
 Then explore the distribution of earthquake magnitudes using Observable Plot:
 
 ```js echo
-Plot.plot({
-  marks: [
-    Plot.rectY(quakeData, Plot.binX({y: "count"}, {x: "mag", interval: 0.5}))
-  ]
-})
+Plot.rectY(quakes, Plot.binX({y: "count"}, {x: "mag"})).plot()
 ```