Build and deploy the website with GitHub Actions

.github/workflows/website.yml

@@ -0,0 +1,68 @@
+name: website
+
+on:
+  push:
+    branches:
+      - 'master'
+  pull_request:
+  workflow_dispatch: # Allow for running this manually.
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
+
+jobs:
+  build:
+    name: build website
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+      - name: Install Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: 1.20.x
+      - name: Generate command documentation
+        # This writes the automatically generated documentation in docs/cmd
+        # and docs/output_options.md, which the website build requires.
+        run: go generate .
+      - name: Install Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - name: Install website dependencies
+        run: npm ci
+        working-directory: website
+      - name: Build website
+        run: npx docusaurus-build
+        working-directory: website
+      - name: Upload the built website
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # docusaurus-build writes the site to a subdirectory named after
+          # the projectName in website/siteConfig.js.
+          path: website/build/InMAP
+
+  deploy:
+    name: deploy website
+    # Only publish the website for changes that land on master; for pull
+    # requests and other branches the build job above just checks that the
+    # website still builds.
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,3 +1,11 @@
 vendor/*
 
-.DS_STORE
+.DS_STORE
+
+# Automatically generated by `go generate .` (see internal/autogen.go).
+docs/cmd/
+docs/output_options.md
+
+# Automatically generated when building the website (see website/README.md).
+website/node_modules/
+website/build/

README.md

@@ -51,14 +51,14 @@ You can also compile InMAP from its source code. The instructions here are speci
 3. Create an emissions scenario or use one of the evaluation emissions datasets available in the `evaldata_vX.X.X.zip` files on the [InMAP release page](https://github.com/spatialmodel/inmap/releases). Emissions files should be in [shapefile](http://en.wikipedia.org/wiki/Shapefile) format where the attribute columns correspond to the names of emitted pollutants. The acceptable pollutant names are
 `VOC`, `NOx`, `NH3`, `SOx`, and `PM2_5`. Emissions units can be specified in the configuration file (discussed below) and can be short tons per year,  kilograms per year, or micrograms per second. The model can handle multiple input emissions files, and emissions can be either elevated or ground level. Files with elevated emissions need to have attribute columns labeled "height", "diam", "temp", and "velocity" containing stack information in units of m, m, K, and m/s, respectively. Emissions will be allocated from the geometries in the shape file to the InMAP computational grid.
 
-1. Make a copy of the [configuration file template](eval/nei2005Config.toml) and edit it if desired, keeping in mind that you will either need to set the `evaldata` environment variable to the directory you downloaded the evaluation data to, or replace all instances of `${evaldata}` in the configuration file with the path to that directory. You must also ensure that the directory `OutputFile` is to go in exists. Refer to the documentation [here](docs/cmd/inmap.md) for information about other configuration options. The configuration file is a text file in [TOML](https://github.com/toml-lang/toml) format, and any changes made to the file will need to conform to that format or the model will not run correctly and will produce an error.
+1. Make a copy of the [configuration file template](eval/nei2005Config.toml) and edit it if desired, keeping in mind that you will either need to set the `evaldata` environment variable to the directory you downloaded the evaluation data to, or replace all instances of `${evaldata}` in the configuration file with the path to that directory. You must also ensure that the directory `OutputFile` is to go in exists. Refer to the documentation [here](https://inmap.run/docs/cmd/inmap) for information about other configuration options. The configuration file is a text file in [TOML](https://github.com/toml-lang/toml) format, and any changes made to the file will need to conform to that format or the model will not run correctly and will produce an error.
 
 2. Run the program:
 
 		inmapXXX run steady --config=/path/to/configfile.toml
 	where `inmapXXX` is replaced with the executable file that you [downloaded](https://github.com/spatialmodel/inmap/releases). For some systems you may need to type `./inmapXXX` instead. If you compiled the program from source, the command will just be `inmap` for Linux or Mac systems and `inmap.exe` for Windows systems.
 
-	The above command runs the model in the most typical mode. For alternative run modes and other command options refer [here](docs/cmd/inmap.md).
+	The above command runs the model in the most typical mode. For alternative run modes and other command options refer [here](https://inmap.run/docs/cmd/inmap).
 
 3. View the program output. The output files are in [shapefile](http://en.wikipedia.org/wiki/Shapefile) format which can be viewed in most GIS programs. One free GIS program is [QGIS](http://www.qgis.org/). By default, the InMAP only outputs ground-level, but this can be changed using the configuration file.
 
@@ -68,7 +68,7 @@ You can also compile InMAP from its source code. The instructions here are speci
 
 	Output variable expressions are, by default, evaluated within each grid cell. By surrounding an expression with braces ({...}), InMAP can instead perform summary calculations (evaluating the expression across all grid cells). InMAP has a built-in function `sum()` that can be used for such grid level calculations. For example, an expression for a variable `NPctWNoLat`, representing the percentage of the total US population that is Non-Latino White, would be `NPctWNoLat = "{sum(WhiteNoLat) / sum(TotalPop)}"`. Only the part of the expression inside of the braces is evaluated at the grid level. `NPctWNoLat` could then be used as a variable in expressions evaluated at the grid cell level, e.g, `WhNoLatDiff = "PctWhNoLat - NPctWNoLat"`, representing the difference between the percentage of the population of each grid cell that is white and the percentage of the total US population that is white.
 
-	There is a complete list of built-in variables [here](docs/output_options.md). Some examples include:
+	There is a complete list of built-in variables [here](https://inmap.run/docs/output_options). Some examples include:
 	* Pollutant concentrations in units of μg m<sup>-3</sup>:
 	  * VOC (`VOC`)
 		* NO<sub>x</sub> (`NOx`)
@@ -94,7 +94,7 @@ InMAP includes a preprocessor to convert chemical transport model (CTM) output i
 Unlike the main InMAP model, the preprocessor only needs to be run once for each spatiotemporal domain.
 Users that would like to use a different spatial or temporal domain than what is included with the InMAP download can obtain CTM output for that domain and run the preprocessor themselves.
 The WRF-Chem and GEOS-Chem CTMs are currently supported.
-Information on how to run the preprocessor is [here](docs/cmd/inmap_preproc.md), and information regarding preprocessor configuration is [here](https://godoc.org/github.com/spatialmodel/inmap/inmaputil#ConfigData.Preproc).
+Information on how to run the preprocessor is [here](https://inmap.run/docs/cmd/inmap_preproc), and information regarding preprocessor configuration is [here](https://godoc.org/github.com/spatialmodel/inmap/inmaputil#ConfigData.Preproc).
 
 ## API
 

RELEASE.md

@@ -16,4 +16,6 @@ This file contains a checklist for steps to take to release a new version of InM
 
 1. Create a release on github and add any new input or evaluation data as downloads.
 
-1. Github actions will automatically add precompiled binaries to the release.
+1. Github actions will automatically add precompiled binaries to the release.
+
+1. Github actions will automatically rebuild and redeploy the website; no manual step is needed.