feat: Use makefile targets for document linting (#215)

This Makefile provides several targets for linting
documents. It utilizes several npm packages.
Functionality includes:

* Spellcheck
* Linting of markdown
* Check for broken links
* Sorting of dictionary file
* Detect inconsidered language

All targets (excluding the sorting of the dict file) are part
of the Github Action pipeline and will fail if quality
standards are not met.

Signed-off-by: Johannes Amorosa <johannes.amorosa@endocode.com>

.alexrc.yaml

@@ -0,0 +1,4 @@
+allow:
+  - German
+  - german
+  - european

.github/workflows/checks.yml

@@ -0,0 +1,40 @@
+name: Checks
+
+on: [push]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install requirements
+        run: |
+          sudo apt install -y automake npm nodejs
+
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Install npm dependencies
+        if: always()
+        run: |
+          make install
+
+      - name: Linting markdown
+        if: always()
+        run: |
+          make markdownlint
+
+      - name: Checking for broken links
+        if: always()
+        run: |
+          make checklinks
+
+      - name: Spellchecking english
+        if: always()
+        run: |
+          make spellcheck-en
+
+      - name: Detect inconsiderate language
+        if: always()
+        run: |
+          make detect-inconsiderate-language

.gitignore

@@ -1 +1,2 @@
 .DS_STORE
+node_modules

.spelling

@@ -0,0 +1,28 @@
+backend
+Backend
+Bundesbeauftragter
+Bundesnetzagentur
+Commonmark
+coronavirus
+Covid-19
+Deutsche
+e.g.
+en_US
+Gesundheitsamt
+Informationsfreiheit
+Infrastrukturen
+iOS
+Kritische
+linter
+macOS
+Metadata
+npm
+Probenbegleitschein
+pseudonymized
+RPIs
+SARS-CoV-2
+TalkBack
+Telekom
+TeleTAN
+tl;dr
+UI

CONTRIBUTING.md

@@ -1,10 +1,14 @@
 # Contributing
 
+## Build status
+
+![Checks](https://github.com/corona-warn-app/cwa-documentation/workflows/Checks/badge.svg)
+
 ## Code of Conduct
 
 All members of the project community must abide by the [Contributor Covenant, version 2.0](CODE_OF_CONDUCT.md).
 Only by respecting each other we can develop a productive, collaborative community.
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [corona-warn-app.opensource@sap.com](mailto:corona-warn-app.opensource@sap.com) and/or a project maintainer. 
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting [corona-warn-app.opensource@sap.com](mailto:corona-warn-app.opensource@sap.com) and/or a project maintainer.
 
 We appreciate your courtesy of avoiding political questions here. Issues which are not related to the project itself will be closed by our community managers. 
 
@@ -38,7 +42,8 @@ The following rule governs code contributions:
 
 ## Contributing Documentation
 
-You are welcome to contribute documentation to the project.
+You are welcome to contribute documentation to the project. Please see the
+installation [document](INSTALL.md)
 
 The following rule governs documentation contributions:
 
@@ -64,7 +69,7 @@ The following rule governs documentation contributions:
 
 ## Issues and Planning
 
-* We use GitHub issues to track bugs and enhancement requests. 
+* We use GitHub issues to track bugs and enhancement requests.
 
 * Please provide as much context as possible when you open an issue. The information you provide must be comprehensive enough to reproduce that issue for the assignee. Therefore, contributors should use but aren't restricted to the issue template provided by the project maintainers.
 

INSTALL.md

@@ -0,0 +1,163 @@
+# Development on documentation
+
+## tl;dr
+
+**You will need to use following `make targets` before creating a pull request!**
+
+1. `make install`
+2. `make check`
+
+## Features
+
+* Linting of markdown documents
+* Spell checking
+* Link checking
+
+## Specifications
+
+This repository checks against following specification:
+
+* [Markdown Commonmark](https://spec.commonmark.org/)
+
+### Languages
+
+Supported languages are:
+
+* [English US](https://en.wikipedia.org/wiki/ISO/IEC_8859-1)
+
+## Prerequisites
+
+To run all the linters please install for your OS:
+
+* [npm](https://github.com/nodesource/distributions)
+
+## Installation
+
+For linting and all the checks you need several npm packages. The following
+command installs all necessary npm dependencies:
+
+```shell
+make install
+```
+
+This installs all dependencies into a local `node_modules` folder. `Make` adds
+this to your execution path automatically. If you install the modules somewhere
+else please make sure this folder is in your execution path. On macOS or Linux
+you probably need to export your Path like this:
+
+```shell
+export PATH=my/path/to/node_modules/.bin:$PATH
+```
+
+## Checks
+
+To enforce good spelling and specification conformity there are several checks
+as `Makefile` targets defined. To run all checks please execute:
+
+```shell
+make check
+```
+
+As an alternative to make it is possible to utilize *npm-run-all* for testing:
+
+```shell
+npm run-script test
+```
+
+### Individual checks
+
+If you want to run individual checks see the targets and the description below.
+There are always Makefile targets. If you prefer npm for testing you can run
+every individual check like so:
+
+```shell
+npm runscript my-individual-check
+```
+See the package-json file for help.
+
+#### Markdown linter
+
+Markdown linting. See the rules [here](https://github.com/DavidAnson/markdownlint).
+
+```shell
+make markdownlint
+```
+
+##### Overrides
+
+Sometimes it is not possible to be commonmark conform. In this
+rare cases an inline tag to skip linting is possible.
+
+Candidates are tables.
+
+```html
+<!-- markdownlint-disable-->
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+<!-- markdownlint-enable-->
+```
+
+Additionally html image tags can be allowed globally. This is useful if you need
+to resize images, since commonmark has no annotation for this.
+
+This is done with a .markdownlint.json override file which would look something
+like this:
+
+```json
+{
+    "no-inline-html": {
+        "allowed_elements": [
+            "img",
+            "table"
+        ]
+    }
+}
+```
+
+For more information how to tweak overrides consult the markdown linter
+documentation mentioned above.
+
+#### Spell checker
+
+##### English
+
+Spell checking in American English (en_US).
+
+```shell
+make spellcheck-en
+```
+
+##### German
+
+Not implemented yet.
+
+##### Overrides
+
+Add any additional words to the .spelling file and use the make target to sort
+and clean them before adding these to master.
+
+```shell
+make format-spelling
+```
+
+Please note sometimes overriding is not the way to go. For example there may be
+three ways for the word TeleTan (TeleTAN, teleTAN) in this repository. The
+documents should stick to one variation.
+
+#### Link resolver
+
+All cross references and external URLs are resolved.
+
+```shell
+make checklinks
+```
+
+#### Inconsiderate language scanner
+
+This checks against profanity and inconsiderate language. This is help full for
+non-natives to detect words that could be inconsiderate. This utilizes
+[alex](https://github.com/get-alex/alex)
+
+```shell
+make detect-inconsiderate-language
+```

Makefile

@@ -0,0 +1,34 @@
+.PHONY: all install check markdownlint clean checklinks spellcheck-en spellcheck detect-inconsiderate-language
+
+SHELL := /bin/bash
+export PATH := ./node_modules/.bin:$(PATH)
+
+install:
+	# https://stackoverflow.com/a/56254478
+	npm ci
+
+check: markdownlint checklinks spellcheck format-spelling detect-inconsiderate-language
+spellcheck: spellcheck-en
+
+spellcheck-en:
+	mdspell '**/*.md' --en-us -t -n -a --report \
+	'!**/node_modules/**/*.md' \
+	'!**/.github/**/*.md' \
+	'!**/translations/**/*.md'
+
+markdownlint:
+	markdownlint '**/*.md' --ignore node_modules
+
+checklinks:
+	# https://github.com/tcort/markdown-link-check/issues/57
+	find . -not -path "*node_modules*" -not -path "*.github*" -name \*.md | \
+	xargs -n 1 markdown-link-check
+
+detect-inconsiderate-language:
+	alex
+
+format-spelling:
+	sort < .spelling | sort | uniq | tee .spelling.tmp > /dev/null && mv .spelling.tmp .spelling
+
+clean:
+	rm -rf node_modules

README.md

@@ -4,7 +4,7 @@
 
 <hr />
 <p align="center">
-    <a href="#about-this-project">About this Project</a> • 
+    <a href="#about-this-project">About this Project</a> •
     <a href="#who-we-are">Who We Are</a> •
     <a href="#credits">Credits</a> •
     <a href="#data-privacy">Data Privacy</a> •
@@ -54,7 +54,7 @@ The project scope has been agreed on jointly by Deutsche Telekom AG and SAP SE a
 - [Corona-Warn-App - User Interface Screens](ui_screens.md)
 
 ### Technical Documentation
-The technical documents are intended for a technical audience and represent the most recent state of the architecture. The solution architecture and concepts might change over time as external dependencies (e.g. the framework provided by Apple/Google) are still changing and new requirements need to be included or existing ones change. We appreciate feedback to all elements of these technical documents. 
+The technical documents are intended for a technical audience and represent the most recent state of the architecture. The solution architecture and concepts might change over time as external dependencies (e.g. the framework provided by Apple/Google) are still changing and new requirements need to be included or existing ones change. We appreciate feedback to all elements of these technical documents.
 
 * [Corona-Warn-App - Solution Architecture](solution_architecture.md)
 * [Corona-Warn-App Server Architecture](https://github.com/corona-warn-app/cwa-server/blob/master/docs/ARCHITECTURE.md)
@@ -80,7 +80,7 @@ For an easier understanding of the used acronyms and special terms in our docume
 
 Copyright (c) 2020 Deutsche Telekom AG and SAP SE or an SAP affiliate company.
 
-Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this file except in compliance with the License. 
+Licensed under the **Apache License, Version 2.0** (the "License"); you may not use this file except in compliance with the License.
 
 You may obtain a copy of the License at https://www.apache.org/licenses/LICENSE-2.0.