uv pip and events

Author: Billy Charlton

docs/intro-help.md

@@ -13,9 +13,9 @@ Then you can start modifying the configuration YAML files to experiment with set
 
 ## Asking questions and making suggestions
 
-The best place to ask a question is to file a [GitHub issue here](https://github.com/simwrapper/simwrapper/issues). That way, others can also see the question and eventual responses and answers.
+The best place to ask a question is the [SimWrapper discussion board(https://github.com/orgs/simwrapper/discussions) on GitHub. That way, others can also see the question and eventual responses and answers.
 
-- Please label your questions with the label `Question` so we can better filter them from the long list of open bugs and issues.
+- Please label your questions with the label `Q&A` if you're looking for help.
 
 ## Filing bug reports / issues
 

docs/intro-running-locally.md

@@ -0,0 +1,51 @@
+---
+id: running-locally
+title: Running it locally
+---
+
+If you want to run SimWrapper on your own server or laptop, there are a few ways to do so.
+
+### Install from uv/pip
+
+This is the easiest solution for most of you. SimWrapper is a website, but for ease of of local installation we've also packaged it up as a super simple 'simwrapper' command-line package on the PyPi software repository. You don't need to know Python to use this package.
+
+**Shortest path to a running local installation:**
+
+- Install the [uv software manager](https://docs.astral.sh/uv/getting-started/installation/) which is the most modern Python packaging ecosystem out there.
+  It is far, far faster and more error-proof than using pip or other methods.
+- Run `uv tool install simwrapper` to install simwrapper as a command-line program on your system.
+  Read the output from the install command; you might need to edit your PATH to include the program.
+- Now go to the folder containing the data you want to explore, and run `uv tool run simwrapper`
+- That's it! Your site is running at http://localhost:4999
+
+You can upgrade with `uv tool upgrade simwrapper`
+
+**pip**
+
+You can also use pip directly, with `pip install simwrapper`. If you go this route, you should
+probably create a virtualenv (venv) and make sure you have a recent version of Python. These extra
+steps can be a real pain, especially because the tool has many datascience dependencies which are
+difficult to install. Please use `uv` instead, as above :-) 
+
+
+### Use Docker
+
+SimWrapper is available as a built Docker image at https://hub.docker.com/r/simwrapper/app
+
+Let's assume you already know how to use Docker if you are reading this!
+
+- `docker pull simwrapper/app` 
+- `docker run -p 4999:4999 -v /my/data/folder:/data simwrapper/app`
+
+The `-p` tells docker to listen on port 4999; `-v` links your local folder of files to `/data` in
+the container image, where simwrapper will then be able to access them.
+
+
+### Build the site yourself
+
+Please read the [developer's guide](dev-guide) for full instructions on how to build and run the
+site locally.
+
+This should only be necessary if you want to file/fix bugs or add special features for your own
+instance. PR's gladly accepted!
+

docs/matsim-events.md

@@ -10,19 +10,17 @@ _MATSim event animation_
 
 **The event viewer is under development and is not yet released. We are currently researching the best way to ingest the very large MATSim event files in a streaming manner, in order to produce useful animations or other visualizations from them.**
 
-If you have specific use cases for a MATSim event viewer, please let us know! We would definitely like to add this in the future.
+If you have specific use cases for a MATSim event viewer, please let us know! We would definitely like to add this as a full-featured visualization in the near future.
 
-
-<!--- _Currently, we can load an_ `output_events.xml.gz` _file but it takes a very long time (many minutes for a typical simulation), and then the vehicle animation displays but does not yet have any configuration._
+_Currently, we can load an_ `output_events.xml.gz` _file but it loads a bit slowly, and then the vehicle animation displays but does not yet have any configuration._
 
 _This is a technology test; feel free to try it out. We will hopefully update it to be more featureful soon._
 
 
 ## Usage
 
-If the file `output_events.xml.gz` exists in a folder, the events viewer panel will be available. There is no YAML configuration available.
-
-Event animations cannot be embedded in a dashboard.
+- Go to the "Files" tab of any SimWrapper file browser or dashboard page.
+- If the file `*output_events.xml.gz` exists in a folder, the events viewer panel will be available. There is no YAML configuration available.
 
+Event animations cannot be embedded in a dashboard yet.
 
--->

website/sidebars.json

@@ -1,6 +1,6 @@
 {
   "doc": {
-    "Introduction": ["index", "examples", "file-management", "help"],
+    "Introduction": ["index", "examples", "file-management", "running-locally", "help"],
     "Guides": [
       "guide-getting-started",
       "guide-dashboards-from-code",