align Makefile with other VSHN docs projects

Author: tobru

.github/workflows/test.yml

@@ -10,8 +10,7 @@ jobs:
     strategy:
       matrix:
         command:
-          - lint_yaml
-          - docs-vale
+          - check
     steps:
       - uses: actions/checkout@v2
       - name: Run ${{ matrix.command }}
@@ -23,7 +22,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: snow-actions/eclint@v1.0.1
         with:
-          args: 'check'
+          args: "check"
 
   docs:
     runs-on: ubuntu-latest

Makefile

@@ -1,38 +1,24 @@
-MAKEFLAGS += --warn-undefined-variables
-SHELL := bash
-.SHELLFLAGS := -eu -o pipefail -c
-.DEFAULT_GOAL := all
-.DELETE_ON_ERROR:
-.SUFFIXES:
+pages   := $(shell find . -type f -name '*.adoc')
+out_dir := ./_public
 
-ANTORA_PREVIEW_CMD ?= $(DOCKER_CMD) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora vshn/antora-preview:3.0.1.1 --style=syn --antora=docs
+docker_cmd  ?= docker
+docker_opts ?= --rm --tty --user "$$(id -u)"
 
-DOCKER_CMD  ?= docker
-DOCKER_ARGS ?= run --rm --user "$$(id -u)" --volume "$${PWD}:/src" --workdir /src
-
-YAML_FILES      ?= $(shell find . -type f -name '*.yaml' -or -name '*.yml')
-YAMLLINT_ARGS   ?= --no-warnings
-YAMLLINT_CONFIG ?= .yamllint.yml
-YAMLLINT_IMAGE  ?= docker.io/cytopia/yamllint:latest
-YAMLLINT_DOCKER ?= $(DOCKER_CMD) $(DOCKER_ARGS) $(YAMLLINT_IMAGE)
-
-VALE_CMD  ?= $(DOCKER_CMD) $(DOCKER_ARGS) --volume "$${PWD}"/docs/modules:/pages vshn/vale:2.1.1
-VALE_ARGS ?= --minAlertLevel=error --config=/pages/ROOT/pages/.vale.ini /pages
+vale_cmd ?= $(docker_cmd) run $(docker_opts) --volume "$${PWD}"/docs/modules/ROOT/pages:/pages --workdir /pages docker.io/vshn/vale:2.10.5.1 --minAlertLevel=error /pages
+preview_cmd ?= $(docker_cmd) run --rm --publish 35729:35729 --publish 2020:2020 --volume "${PWD}":/preview/antora docker.io/vshn/antora-preview:3.1.1.1 --antora=docs --style=syn
 
 .PHONY: all
-all: lint docs open
-
-.PHONY: lint
-lint: lint_yaml docs-vale
+all: html
 
-.PHONY: lint_yaml
-lint_yaml: $(YAML_FILES)
-	$(YAMLLINT_DOCKER) -f parsable -c $(YAMLLINT_CONFIG) $(YAMLLINT_ARGS) -- $?
+# This will clean the Antora Artifacts, not the npm artifacts
+.PHONY: clean
+clean:
+	rm -rf $(out_dir) '?' .cache
 
-.PHONY: docs-serve
-docs-serve:
-	$(ANTORA_PREVIEW_CMD)
+.PHONY: check
+check:
+	$(vale_cmd)
 
-.PHONY: docs-vale
-docs-vale:
-	$(VALE_CMD) $(VALE_ARGS)
+.PHONY: preview
+preview:
+	$(preview_cmd)

README.md

@@ -1,12 +1,13 @@
 # Project Syn Documentation
 
-This is the umbrella documentation for project syn.
-It is written using [Asciidoc][asciidoc] and [Antora][antora] and located in the [docs/](docs) folder.
+This is the umbrella documentation for Project Syn.
+
+It is written using [AsciiDoc][asciidoc] and [Antora][antora]. The source is located in the [docs/](docs) folder.
 The [Divio documentation structure](https://documentation.divio.com/) is used to organize its content.
 
-Run the `make docs-serve` command in the root of the project, and then browse to http://localhost:2020 to see a preview of the documentation.
+Run the `make preview` command in the root of the project, and then browse to http://localhost:2020 to see a preview of the documentation.
 
-After writing the documentation, please use the `make docs-vale` command and correct any warnings raised by the tool.
+After writing the documentation, please use the `make check` command and correct any warnings raised by the tool.
 
 ## Contributing and license
 

docs/modules/ROOT/pages/.vale.ini

@@ -3,7 +3,6 @@ MinAlertLevel = warning # suggestion, warning or error
 
 # Only check Asciidoc files
 [*.adoc]
-
-# Using the Microsoft style
 BasedOnStyles = Microsoft
-Microsoft.GenderBias = warning
+Microsoft.GenderBias = suggestion
+Openly.GenderBias = suggestion

docs/modules/ROOT/pages/references/style-guide.adoc

@@ -390,7 +390,7 @@ animal.newAnimal("Finnegan",
 ==== File structure
 
 * Jsonnet files which are intended to be materialized should end with the `.jsonnet` suffix.
-* Jsonnet files which aren't intended to be materialized -- usually libraries -- should end with the `.libjsonnet` suffix.
+* Jsonnet files which aren't intended to be materialized (usually libraries) should end with the `.libjsonnet` suffix.
 * Files in `lib` always are libraries which should never be materialized and must be named accordingly.
   Those files are considered part of a public API.
   Treat functions in libraries accordingly and look out for breaking changes.