Merge branch 'markdown' into 'master'

Markdown Closes #456 See merge request ghsc/nshmp/nshmp-haz-v2!510

Merge branch 'markdown' into 'master'
d5b5897f · Powers, Peter M. · 7082888b · 814c8668 · d5b5897f · d5b5897f
Commit d5b5897f authored 4 years ago by Powers, Peter M.
--- a/.gitignore
+++ b/.gitignore
@@ -23,3 +23,7 @@ config.properties
 libs
 .factorypath
 .apt_generated*
+# Node
+node_modules
+package-lock.json
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
 variables:
+  IMAGE_NAME: ${CODE_REGISTRY_IMAGE}/${CI_PROJECT_NAME}
  JACOCO_HTML_DIR: build/reports/jacoco/test/html
  JUNIT_FILES: build/test-results/test/TEST-*.xml
@@ -8,6 +9,7 @@ include:
    file: 'templates/library.yml'
 stages:
+  - image
  - build
  - publish
@@ -19,7 +21,7 @@ stages:
  extends:
    - .tags::development
  stage: build
-  image: ${DEVOPS_REGISTRY}usgs/java:11
+  image: ${IMAGE_NAME}
 .docker-build:
  extends:
@@ -37,6 +39,34 @@ stages:
    DOCKERFILE: Dockerfile
    IMAGE_NAME: ${CI_PROJECT_NAME}
+####
+# Stage: image
+####
+Image:
+  extends:
+    - .dind
+  rules:
+    -
+      changes:
+        - .gitlab/Dockerfile
+      when: on_success
+    -
+      allow_failure: true
+      when: manual
+  script:
+    - |
+      docker build \
+        --build-arg FROM_IMAGE=${DEVOPS_REGISTRY}usgs/node:12 \
+        --file ".gitlab/Dockerfile" \
+        --pull \
+        --tag ${IMAGE_NAME} \
+        .
+    - docker push ${IMAGE_NAME}
+  stage: image
+  tags:
+    - build
 ####
 # Stage: build
 ####
@@ -44,33 +74,57 @@ stages:
 Build Project:
  extends:
    - .gradle
+  rules:
+    -
+      changes:
+        - '**/*.java'
+      when: on_success
+    -
+      allow_failure: true
+      when: manual
  script:
    - ./gradlew assemble
 Build Lambda:
-  extends:
-    - .gradle
-  script:
-    - ./gradlew assemble
-    - ./gradlew libs
  artifacts:
    expire_in: 1 yr
    paths:
      - build/libs/nshmp-haz-v2.jar
      - build/libs/nshmp-haz-dependencies.zip
-Unit Tests:
  extends:
    - .gradle
-  coverage: '/Total.*?([0-9]{1,3})%/'
+  rules:
+    -
+      changes:
+        - '**/*.java'
+      when: on_success
+    -
+      allow_failure: true
+      when: manual
  script:
-    - ./gradlew check
+    - ./gradlew assemble
-    - cat ${JACOCO_HTML_DIR}/index.html
+    - ./gradlew libs
+Unit Tests:
  artifacts:
    paths:
      - ${JACOCO_HTML_DIR}
    reports:
      junit: ${JUNIT_FILES}
+  coverage: '/Total.*?([0-9]{1,3})%/'
+  extends:
+    - .gradle
+  rules:
+    -
+      changes:
+        - '**/*.java'
+      when: on_success
+    -
+      allow_failure: true
+      when: manual
+  script:
+    - ./gradlew check
+    - cat ${JACOCO_HTML_DIR}/index.html
 Build Haz Image:
  extends:
@@ -89,20 +143,14 @@ Build WS Image:
 # Stage: Publish
 ####
-Maven:
+Trigger AWS nshmp-haz:
-  extends:
+  rules:
-    .gradle
+    -
-  stage: publish
+      if: '$CI_PROJECT_NAMESPACE == "ghsc/nshmp" && $CI_COMMIT_TAG'
-  only:
+    -
-    - tags@ghsc/nshmp/nshmp-ws
+      changes:
-  script:
+        - 'src/main/java/gov/usgs/earthquake/nshmp/aws/**/*.java'
-    - ./gradlew publish -P version=${CI_COMMIT_TAG}
+        - 'gradle/dependencies.gradle'
-Trigger nshmp-deploy:
-  stage: publish
-  only:
-    - master@ghsc/nshmp/nshmp-haz-v2
-    - tags@ghsc/nshmp/nshmp-haz-v2
  script:
    - apk add curl
    - |
@@ -110,3 +158,4 @@ Trigger nshmp-deploy:
          -F token=${NSHMP_DEPLOY_TRIGGER_TOKEN} \
          -F ref=master \
          https://code.chs.usgs.gov/api/v4/projects/5047/trigger/pipeline
+  stage: publish
--- a/.gitlab/Dockerfile
+++ b/.gitlab/Dockerfile
+ARG FROM_IMAGE=usgs/node:12
+FROM ${FROM_IMAGE}
+ENV LANG="en_US.UTF-8"
+USER root
+RUN yum install -y git glibc-langpack-en java-11-openjdk-devel which \
+    && yum clean all
+USER usgs-user
--- a/.markdownlint.yml
+++ b/.markdownlint.yml
+##
+# Rules for markdownlint.
+#
+# See https://github.com/DavidAnson/markdownlint
+##
+default: true
+# MD013/line-length - Line length
+MD013:
+  # Number of characters
+  line_length: 100
+  # Number of characters for headings
+  heading_line_length: 100
+  # Number of characters for code blocks
+  code_block_line_length: 100
--- a/.markdownlintignore
+++ b/.markdownlintignore
+.settings
+bin
+build
+tmp
+libs
+node_modules
--- a/ACKNOWLEDGEMENTS.md
+++ b/ACKNOWLEDGEMENTS.md
-This software was developed to meet the U.S. Geological Survey's need for a high-performance probabilistic seismic hazard (PSHA) engine capable of supporting increasingly complex earthquake hazard models via web-services. It leverages and benefits from many design and performance features found in [OpenSHA](http://www.opensha.org) and the legacy [USGS fortran codes](/usgs/nshmp-haz-fortran), both of which have been supported by the USGS and others over many years. In particular, the Southern California Earthquake Center ([SCEC](https://www.scec.org)) has been instrumental in the continued development of OpenSHA, which is in use worldwide.
+# Acknowledgements
-This software is not a replacement for OpenSHA and does not provide a public API for PSHA development. In the near future, `nshmp-haz` will likely be added as a dependency in OpenSHA so that it's users may gain access to the most current USGS hazard models.
+This software was developed to meet the U.S. Geological Survey's need for a
+high-performance probabilistic seismic hazard (PSHA) engine capable of supporting
+increasingly complex earthquake hazard models via web-services. It leverages and
+benefits from many design and performance features found in
+[OpenSHA](http://www.opensha.org) and the legacy [USGS fortran codes](/usgs/nshmp-haz-fortran),
+both of which have been supported by the USGS and others over many years. In particular,
+the Southern California Earthquake Center ([SCEC](https://www.scec.org)) has been instrumental
+in the continued development of OpenSHA, which is in use worldwide.
+This software is not a replacement for OpenSHA and does not provide a public API for PSHA
+development. In the near future, `nshmp-haz` will likely be added as a dependency in OpenSHA
+so that it's users may gain access to the most current USGS hazard models.
--- a/DISCLAIMER.md
+++ b/DISCLAIMER.md
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# Disclaimer
-Information provided by this software may be preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The information is provided on the condition that neither the U.S. Geological Survey nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the information.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+Information provided by this software may be preliminary or provisional and is subject to
+revision. It is being provided to meet the need for timely best science. The information is
+provided on the condition that neither the U.S. Geological Survey nor the U.S. Government
+shall be held liable for any damages resulting from the authorized or unauthorized use of the information.
--- a/LICENSE.md
+++ b/LICENSE.md
-Unless otherwise noted, this software is in the public domain because it contains materials that originally came from the U.S. Geological Survey (USGS), an agency of the U.S. Department of Interior. For more information, see the official USGS [copyright policy](http://www.usgs.gov/visual-id/credit_usgs.html#copyright).
+# License
-Dependent libraries managed by the [Gradle](https://gradle.org) build tool are distributed under open source (or open source-like) licenses. Links to appropriate license agreements for each can be found below.
+Unless otherwise noted, this software is in the public domain because it contains materials
+that originally came from the U.S. Geological Survey (USGS), an agency of the U.S. Department
+of Interior. For more information, see the official USGS
+[copyright policy](http://www.usgs.gov/visual-id/credit_usgs.html#copyright).
-#### Runtime language and libraries:
+Dependent libraries managed by the [Gradle](https://gradle.org) build tool are distributed
+ under open source (or open source-like) licenses. Links to appropriate license agreements
+ for each can be found below.
+## Runtime language and libraries
 - [Java 8](http://www.oracle.com/technetwork/java/javase/terms/license)
 - [Google Guava 26.0](https://github.com/google/guava/blob/master/COPYING)
 - [Google Gson 2.8.5](https://github.com/google/gson/blob/master/LICENSE)
-#### Build tools and libraries:
+## Build tools and libraries
- - [Gradle](https://github.com/gradle/gradle/blob/master/LICENSE)
+- [Gradle](https://github.com/gradle/gradle/blob/master/LICENSE)
- - [JUnit](http://junit.org/junit4/license.html)
+- [JUnit](http://junit.org/junit4/license.html)
- - [JaCoCo](http://www.jacoco.org/jacoco/trunk/doc/license.html)
+- [JaCoCo](http://www.jacoco.org/jacoco/trunk/doc/license.html)
--- a/README.md
+++ b/README.md
-## nshmp-haz
+# nshmp-haz
-![pipeline](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/badges/master/pipeline.svg)
-![coverage](https://code.usgs.gov/ghsc/nshmp/nshmp-haz-v2/badges/master/coverage.svg)
 U.S. Geological Survey ([USGS](https://www.usgs.gov)) National Seismic Hazard Mapping Project
 ([NSHMP](https://earthquake.usgs.gov/hazards/)) code for performing probabilistic seismic hazard

--- a/build.gradle
+++ b/build.gradle
@@ -30,8 +30,9 @@
 plugins {
  id "application"
  id "com.diffplug.gradle.spotless" version "${spotlessVersion}"
-  id "com.github.spotbugs" version "${spotbugsVersion}"
  id "com.github.johnrengelman.shadow" version "${shadowVersion}"
+  id "com.github.node-gradle.node" version "${nodeVersion}"
+  id "com.github.spotbugs" version "${spotbugsVersion}"
  id "com.star-zero.gradle.githook" version "${githooksVersion}"
  id "eclipse-wtp"
  id "jacoco"
@@ -109,7 +110,8 @@ gradle.afterProject {
    }
    into nshmpLib
  }
-  apply from: "${nshmpLibGradleDir}/spotbugs.gradle"
  apply from: "${nshmpLibGradleDir}/git-hooks.gradle"
+  apply from: "${nshmpLibGradleDir}/markdownlint.gradle"
+  apply from: "${nshmpLibGradleDir}/spotbugs.gradle"
  apply from: "${nshmpLibGradleDir}/spotless.gradle"
 }
--- a/etc/README.md
+++ b/etc/README.md
+# ETC
 See the [examples](examples) directory as a starting point for command-line use of `nshmp-haz`.
 [Matlab](matlab) shows how to take advantage of the ground motion model implementations in `nshmp-haz`.

--- a/etc/examples/1-hazard-curve/README.md
+++ b/etc/examples/1-hazard-curve/README.md
-Example 1: A simple hazard calculation
+# Example 1: A simple hazard calculation
--------------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/1-hazard-curve`
@@ -9,16 +8,31 @@ On the command line, navigate to the directory above and execute the following:
 hazard ../../peer/models/Set1-Case1 "Test Site, -122.0, 38.0"
 ```
-The PEER models, such as that designated above, consist of simple cases for different source types commonly encountered in a PSHA and are included in the nshmp-haz repository to support testing. See the [PEER directory](../../peer/) for more information.
+The PEER models, such as that designated above, consist of simple cases for different source
+types commonly encountered in a PSHA and are included in the nshmp-haz repository to support
+testing. See the [PEER directory](../../peer/) for more information.
-The result of this calculation should be available as a single comma-delimited file containing several total mean hazard curves for PGA in a newly created `hazout` directory. In this example, the calculation configuration was derived from the model directory and the site was specified as a comma-delimited string. The string must have the form: `name,lon,lat[,vs30,vsInf[,z1p0,z2p5]]`, where `vs30`, `vsInf`, `z1p0`, and `z2p5` are optional. See the [site specification](https://github.com/usgs/nshmp-haz/wiki/sites) page for more details.
+The result of this calculation should be available as a single comma-delimited file containing
+several total mean hazard curves for PGA in a newly created `hazout` directory. In this example,
+ the calculation configuration was derived from the model directory and the site was specified
+  as a comma-delimited string. The string must have the form:
+   `name,lon,lat[,vs30,vsInf[,z1p0,z2p5]]`, where `vs30`, `vsInf`, `z1p0`, and `z2p5`
+   are optional. See the [site specification](https://github.com/usgs/nshmp-haz/wiki/sites)
+   page for more details.
-Note that not all [calculation configuration](https://github.com/usgs/nshmp-haz/wiki/Configuration) parameters need be supplied; see the [configuration file](../../peer/models/Set1-Case1/config.json) for this example model.
+Note that not all [calculation configuration](https://github.com/usgs/nshmp-haz/wiki/Configuration)
+parameters need be supplied; see the [configuration file](../../peer/models/Set1-Case1/config.json)
+for this example model.
-Also note that all output is written to a `hazout` directory by default, but the output destination can be specified via the [`output.directory`](https://github.com/usgs/nshmp-haz/wiki/configuration#config-output) parameter. In addition to hazard curves, the calculation configuration and a log of the calculation are also saved.
+Also note that all output is written to a `hazout` directory by default, but the output destination
+can be specified via the
+[`output.directory`](https://github.com/usgs/nshmp-haz/wiki/configuration#config-output) parameter.
+In addition to hazard curves, the calculation configuration and a log of the calculation
+are also saved.
 __Results directory structure:__
-```
+```text
 1-hazard-curve/
  └─ hazout/
      ├─ config.json
@@ -29,4 +43,5 @@ __Results directory structure:__
 In the next example, we'll override the model supplied configuration with a custom file.
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 2 – A custom configuration](../2-custom-config)
--- a/etc/examples/2-custom-config/README.md
+++ b/etc/examples/2-custom-config/README.md
-Example 2: A custom configuration
+# Example 2: A custom configuration
-------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/2-custom-config`
@@ -13,13 +12,18 @@ In this example we've overridden the configuration supplied by the model. Specif
 * The upper end of each hazard curve has been truncated at 3 standard deviations.
 * Hazard curves have been saved as poisson probability instead of annual rate.
-* Hazard curves have been calculated for 3 `imts` ([intensity measures](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Imt.html), or spectral periods).
+* Hazard curves have been calculated for 3 `imts`
-* The `imls` (intensity measure levels or x-values) of the resultant curves have been explicitely defined for each `imt`.
+ ([intensity measures](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Imt.html),
+  or spectral periods).
+* The `imls` (intensity measure levels or x-values) of the resultant curves
+have been explicitely defined for each `imt`.
-See the [configuration specification](https://github.com/usgs/nshmp-haz/wiki/configuration) for details on default values and supported options and formats.
+See the [configuration specification](https://github.com/usgs/nshmp-haz/wiki/configuration)
+for details on default values and supported options and formats.
 __Results directory structure:__
-```
+```text
 2-custom-config/
  └─ hazout/
      ├─ config.json
@@ -32,4 +36,5 @@ __Results directory structure:__
          └─ curves.csv
 ```
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 3 – Using a custom sites file](../3-sites-file)
--- a/etc/examples/3-sites-file/README.md
+++ b/etc/examples/3-sites-file/README.md
-Example 3: Using a custom sites file
+# Example 3: Using a custom sites file
------------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/3-sites-file`
-To compute hazard at more than one site, one may supply a comma-delimited (\*.csv) or [GeoJSON](http://geojson.org) (\*.geojson) formatted site data file instead:
+To compute hazard at more than one site, one may supply a comma-delimited (\*.csv)
+ or [GeoJSON](http://geojson.org) (\*.geojson) formatted site data file instead:
 ```Shell
 hazard ../../peer/models/Set1-Case1  sites.csv config.json
@@ -15,12 +15,16 @@ or
 hazard ../../peer/models/Set1-Case1 sites.geojson config.json
 ```
-The [site specification](https://github.com/usgs/nshmp-haz/wiki/sites) wiki page provides details on the two file formats. Note that with either format, if the name of a site is supplied, it will be included in the first column of any output curve files.
+The [site specification](https://github.com/usgs/nshmp-haz/wiki/sites)
+wiki page provides details on the two file formats. Note that with either format,
+if the name of a site is supplied, it will be included in the first column of any output curve files.
-Note that both formats ([CSV](sites.csv) and [GeoJSON](sites.geojson)) are elegantly rendered by GitHub.
+Note that both formats ([CSV](sites.csv) and [GeoJSON](sites.geojson)) are elegantly
+rendered by GitHub.
 __Results directory structure:__
-```
+```text
 3-sites-file/
  └─ hazout/
      ├─ config.json
@@ -33,4 +37,5 @@ __Results directory structure:__
          └─ curves.csv
 ```
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 4 – A simple hazard map](../4-hazard-map)
--- a/etc/examples/4-hazard-map/README.md
+++ b/etc/examples/4-hazard-map/README.md
-Example 4: A simple hazard map
+# Example 4: A simple hazard map
------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/4-hazard-map`
-A hazard map is just a collection of values plucked from a lot of hazard curves. To compute curves at reqularly spaced intervals in latitude and longitude over a region, a [GeoJSON site file](https://github.com/usgs/nshmp-haz/wiki/sites#geojson-format-geojson) may instead specify a polygon and a site spacing.
+A hazard map is just a collection of values plucked from a lot of hazard curves.
+To compute curves at reqularly spaced intervals in latitude and longitude over a region,
+ a [GeoJSON site file](https://github.com/usgs/nshmp-haz/wiki/sites#geojson-format-geojson)
+ may instead specify a polygon and a site spacing.
 ```Shell
 hazard ../../peer/models/Set1-Case1 map.geojson config.json
 ```
 __Results directory structure:__
-```
+```text
 4-hazard-map/
  └─ hazout/
      ├─ config.json
@@ -23,4 +26,5 @@ __Results directory structure:__
          └─ curves.csv
 ```
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 5 – A more complex model](../5-complex-model)
--- a/etc/examples/5-complex-model/README.md
+++ b/etc/examples/5-complex-model/README.md
-Example 5: A more complex model
+# Example 5: A more complex model
-------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/5-complex-model`
-Most PSHAs involve the use of more complex source models, the components of which might use different ground motion models. For this and ensuing examples, we'll use the 2008 USGS National Seismic Hazard Model (NSHM) for the western U.S. `nshmp-haz` uses an in-memory source model. The USGS NSHMs are quite large, so it's helpful to increase the amount memory available to Java when calling `HazardCalc`. For example, set your alias to:
+Most PSHAs involve the use of more complex source models, the components of which
+might use different ground motion models. For this and ensuing examples, we'll use the
+2008 USGS National Seismic Hazard Model (NSHM) for the western U.S. `nshmp-haz` uses an
+in-memory source model. The USGS NSHMs are quite large, so it's helpful to increase the amount
+memory available to Java when calling `HazardCalc`. For example, set your alias to:
 ```Shell
 alias hazard='java -Xms1g -Xmx4g -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc'
 ```
-This will increase the minimum amount of memory Java requires to 1GB and will allow it to claim up to 4GB, assuming that much is available.
+This will increase the minimum amount of memory Java requires to 1GB and will allow it to claim
+up to 4GB, assuming that much is available.
-First, clone the 2008 USGS NSHM. Assuming you are in the current working directory (above), the following will create a copy of the model adjacent to nshmp-haz:
+First, clone the 2008 USGS NSHM. Assuming you are in the current working directory (above), the
+following will create a copy of the model adjacent to nshmp-haz:
 ```Shell
 git clone https://github.com/usgs/nshm-cous-2008.git ../../../../nshm-cous-2008
 ```
-The 2008 NSHM repository contains two source models: one for the western U.S. and a one for the central and eastern U.S. To compute hazard for a few sites in the Western U.S. at 1.0s and 2.0s spectral periods, execute:
+The 2008 NSHM repository contains two source models: one for the western U.S. and a one for the
+central and eastern U.S. To compute hazard for a few sites in the Western U.S. at 1.0s and 2.0s
+spectral periods, execute:
 ```Shell
 hazard ../../../../nshm-cous-2008/Western\ US sites.geojson config-sites.json
 ```
-Note that more complex models take longer to initialize, although this only occurs once per calculation, and make for longer, per-site calculations. However, `HazardCalc` will automatically use all cores available by default and therefore performs better on multi-core systems.
+Note that more complex models take longer to initialize, although this only occurs once per
+calculation, and make for longer, per-site calculations. However, `HazardCalc` will automatically
+use all cores available by default and therefore performs better on multi-core systems.
 To compute a small, low-resolution map for the central San Francisco bay area, execute:
@@ -31,10 +40,13 @@ To compute a small, low-resolution map for the central San Francisco bay area, e
 hazard ../../../../nshm-cous-2008/Western\ US map.geojson config-map.json
 ```
-This computes 121 curves over a 2° by 2° area and will give you a sense of how long a larger map might take. Note that in the above two examples we specified different output directories in the config files for each calculation.
+This computes 121 curves over a 2° by 2° area and will give you a sense of how long a larger map
+might take. Note that in the above two examples we specified different output directories in the
+config files for each calculation.
 __Results directory structure:__
-```
+```text
 5-complex-model/
  ├─ hazout-sites/
  │   ├─ config.json
@@ -53,4 +65,5 @@ __Results directory structure:__
          └─ curves.csv
 ```
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 6 – Enhanced output](../6-enhanced-output)
--- a/etc/examples/6-enhanced-output/README.md
+++ b/etc/examples/6-enhanced-output/README.md
-Example 6: Enhanced output
+# Example 6: Enhanced output
--------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/6-enhanced-output`
-While mean hazard is of broad interest, it can be useful to preserve individual components of a total curve, particularly with more complex models. Execute the following to write curves for each source type and ground motion model (GMM) used in the 2008 NSHM:
+While mean hazard is of broad interest, it can be useful to preserve individual components of a
+total curve, particularly with more complex models. Execute the following to write curves for
+each source type and ground motion model (GMM) used in the 2008 NSHM:
 ```Shell
 hazard ../../../../nshm-cous-2008/Western\ US sites.geojson config.json
 ```
-The [config](https://github.com/usgs/nshmp-haz/blob/master/etc/examples/6-enhanced-output/config.json) file for this example specified `GMM` and `SOURCE` as [output data types](https://github.com/usgs/nshmp-haz/wiki/configuration#calculation-configuration-parameters). Note that the output curves directory now contains additional directories of curves by source type and GMM. We also specified an [output flush limit](https://github.com/usgs/nshmp-haz/wiki/configuration#calculation-configuration-parameters) of `1`. Doing so gives feedback on how long it takes each site calculation to run on a particular system.
+The [config](https://github.com/usgs/nshmp-haz/blob/master/etc/examples/6-enhanced-output/config.json)
+file for this example specified `GMM` and `SOURCE` as
+[output data types](https://github.com/usgs/nshmp-haz/wiki/configuration#calculation-configuration-parameters).
+ Note that the output curves directory now contains additional directories of curves by source
+ type and GMM. We also specified an
+ [output flush limit](https://github.com/usgs/nshmp-haz/wiki/configuration#calculation-configuration-parameters)
+  of `1`. Doing so gives feedback on how long it takes each site calculation to run on a particular system.
-See the `nshmp-haz` wiki and Javacocs for more information on source types ([Wiki](https://github.com/usgs/nshmp-haz/wiki/source-types), [JavaDoc](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/SourceType.html)) and GMMs ([Wiki](https://github.com/usgs/nshmp-haz/wiki/ground-motion-models), [JavaDoc](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Gmm.html)).
+See the `nshmp-haz` wiki and Javacocs for more information on source types
+([Wiki](https://github.com/usgs/nshmp-haz/wiki/source-types),
+[JavaDoc](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/eq/model/SourceType.html))
+ and GMMs ([Wiki](https://github.com/usgs/nshmp-haz/wiki/ground-motion-models),
+  [JavaDoc](http://usgs.github.io/nshmp-haz/javadoc/index.html?gov/usgs/earthquake/nshmp/gmm/Gmm.html)).
 __Results directory structure:__
-```
+```text
 6-enhanced-output/
  └─ hazout/
      ├─ config.json
@@ -39,4 +51,5 @@ __Results directory structure:__
          └─ ...
 ```
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 7 – Deaggregation](../7-deaggregation)
--- a/etc/examples/7-deaggregation/README.md
+++ b/etc/examples/7-deaggregation/README.md
-Example 7: Deaggregation
+# Example 7: Deaggregation
------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/7-deaggregation`
-To perform a deaggregation of hazard, one must use the program `DeaggCalc`. Internally, `DeaggCalc` calls `HazardCalc` and then reprocesses the data to generate a comma-delimited file of distance, magnitude, and epsilon bins, and a text file of summary statistics and primary contributing sources. For this, it can be helpful to create a second system alias:
+To perform a deaggregation of hazard, one must use the program `DeaggCalc`. Internally,
+`DeaggCalc` calls `HazardCalc` and then reprocesses the data to generate a comma-delimited
+file of distance, magnitude, and epsilon bins, and a text file of summary statistics and primary
+contributing sources. For this, it can be helpful to create a second system alias:
 ```Shell
 alias deagg='java -Xms1g -Xmx4g -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.DeaggCalc'
 ```
-`DeaggCalc` is similar to `HazardCalc` in every way except that the return-period of interest must be specified. For example, execute:
+`DeaggCalc` is similar to `HazardCalc` in every way except that the return-period of interest
+must be specified. For example, execute:
 ```Shell
 deagg ../../../../nshm-cous-2008/Western\ US sites.geojson 2475 config.json
 ```
-The results of the deaggregation are saved along with hazard curves in `deagg` directories. As with `HazardCalc`, if the `GMM` ddata type has been specified (as it has in the [config](https://github.com/usgs/nshmp-haz/blob/master/etc/examples/7-deaggregation/config.json) file for this example) additional deaggregation results for each GMM are generated as well. Deaggregations by individual `SOURCE` type are also possible.
+The results of the deaggregation are saved along with hazard curves in `deagg` directories.
+ As with `HazardCalc`, if the `GMM` ddata type has been specified (as it has in the
+ [config](https://github.com/usgs/nshmp-haz/blob/master/etc/examples/7-deaggregation/config.json)
+ file for this example) additional deaggregation results for each GMM are generated as well.
+ Deaggregations by individual `SOURCE` type are also possible.
-See the following pages for more information on [deaggregation](https://github.com/usgs/nshmp-haz/wiki/about-deaggregation) and the meaning of [epsilon](https://github.com/usgs/nshmp-haz/wiki/what-is-epsilon%3F).
+See the following pages for more information on
+[deaggregation](https://github.com/usgs/nshmp-haz/wiki/about-deaggregation)
+and the meaning of [epsilon](https://github.com/usgs/nshmp-haz/wiki/what-is-epsilon%3F).
 __Results directory structure:__
-```
+```text
 7-deaggregation/
  └─ hazout/
      ├─ config.json
@@ -72,6 +82,10 @@ __Results directory structure:__
      └─ SA1P0/
          └─ ...
 ```
-Note that in the output above, there are only deaggregation results for subduction GMMs (e.g. `AB_03_CASCADIA_SLAB`) for sites closer to the Cascadia subduction zone; empty results will not be saved.
+Note that in the output above, there are only deaggregation results for
+subduction GMMs (e.g. `AB_03_CASCADIA_SLAB`) for sites closer to the Cascadia subduction zone;
+empty results will not be saved.
+<!-- markdownlint-disable MD001 -->
 #### Next: [Example 8 – Earthquake probabilities and rates](../8-probabilities)
--- a/etc/examples/8-probabilities/README.md
+++ b/etc/examples/8-probabilities/README.md
-Example 8: Earthquake probabilities and rates
+# Example 8: Earthquake probabilities and rates
---------------------------------------------
 __Working directory:__ `/path/to/nshmp-haz/etc/examples/8-probabilities`
-`nshmp-haz` can also calculate earthquake probabilities and rates at a location. As with the `HazardCalc` and `DeaggCalc` programs, `RateCalc` takes a model, a site data file or string, and an optional config file, which will control whether the distributions generated are incremental or cumulative, and whether the distribution values are expressed as annual rates or Poisson probabilities. The default (no config supplied) settings are for incremental annual-rates. The `config.rate` elements also specify the cutoff `distance`, within which all sources should be included, and a `timespan` used for conversion to Poisson probabilities.
+`nshmp-haz` can also calculate earthquake probabilities and rates at a location.
+As with the `HazardCalc` and `DeaggCalc` programs, `RateCalc` takes a model, a site data file
+or string, and an optional config file, which will control whether the distributions generated
+are incremental or cumulative, and whether the distribution values are expressed as annual rates
+or Poisson probabilities. The default (no config supplied) settings are for incremental
+annual-rates. The `config.rate` elements also specify the cutoff `distance`, within which
+all sources should be included, and a `timespan` used for conversion to Poisson probabilities.
 For this example, the following system alias is helpful:
@@ -25,10 +30,13 @@ rate ../../../../nshm-cous-2008/Western\ US map.geojson config-map.json
 to generate a map of cumulative Poisson probabilities (i.e. P ≥ M).
-Like `HazardCalc`, `RateCalc` observes the `config.output.dataTypes` `SOURCE` option and will include a `source` directory with rates or probabilities for all contributing source types.
+Like `HazardCalc`, `RateCalc` observes the `config.output.dataTypes` `SOURCE`
+option and will include a `source` directory with rates or probabilities for all
+contributing source types.
 __Results directory structure:__
-```
+```text
 8-probabilities/
  ├─ hazout-rate-sites/
  │   ├─ config.json

--- a/etc/examples/README.md
+++ b/etc/examples/README.md
-Examples
+# Examples
--------
-These examples are designed to be executed locally while following the READMEs on GitHub. All examples avoid a lengthy call to Java and the `HazardCalc` program by using the following system alias:
+These examples are designed to be executed locally while following the READMEs on GitHub.
+All examples avoid a lengthy call to Java and the `HazardCalc` program by using the following
+system alias:
 ```Shell
 alias hazard='java -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.earthquake.nshmp.HazardCalc'
@@ -9,4 +10,5 @@ alias hazard='java -cp /path/to/nshmp-haz/build/libs/nshmp-haz.jar gov.usgs.eart
 Because each example builds on prior concepts, it is best step through all the examples, however quickly.
+<!-- markdownlint-disable MD001 -->
 #### Start: [Example 1 – A simple hazard calculation](1-hazard-curve)