Add linting for RST and MD files

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: "Docs"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+    # Only consider changes to documentation
+    paths:
+      - '**/*.md'
+      - '**/*.rst'
+      - '**/*.txt'
+  schedule:
+    - cron: '25 6 * * 3'
+
+permissions:
+  contents: read
+
+jobs:
+  documentation:
+    name: Lint RST and MD files
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@3df4ab11eba7bda6032a0b82a6bb43b11571feac # v4.0.0
+
+      - name: Install rstcheck and markdownlint
+        run: |
+          pip install rstcheck
+          sudo gem install mdl
+
+      - name: Run rstcheck on all RST files
+        run: make checkrst
+
+      - name: Run mdl on all MD files
+        run: make checkmd

CONTRIBUTING.md

@@ -9,6 +9,11 @@ and instructions if you are thinking of helping with the development of SOPS.
   how to install Go [here](https://go.dev/doc/install)
 - Clone the Git repository and switch into SOPS's directory.
 - Run the tests with `make test`. They should all pass.
+- If you modify documentation (RST or MD files), run `make checkdocs` to run
+  [rstcheck](https://pypi.org/project/rstcheck/) and
+  [markdownlint](https://github.com/markdownlint/markdownlint). These should also
+  pass. If you need help in fixing issues, create a pull request (see below) and
+  ask for help.
 - Fork the project on GitHub.
 - Add your fork to Git's remotes:
    - If you use SSH authentication:

Makefile

@@ -20,6 +20,9 @@ SYFT_VERSION        ?= v0.87.0
 GORELEASER          := $(BIN_DIR)/goreleaser
 GORELEASER_VERSION  ?= v1.20.0
 
+RSTCHECK            := $(shell command -v rstcheck)
+MARKDOWNLINT        := $(shell command -v mdl)
+
 export PATH := $(BIN_DIR):$(PATH)
 
 .PHONY: all
@@ -45,6 +48,22 @@ vendor:
 vet:
 	$(GO) vet ./...
 
+
+.PHONY: checkdocs
+checkdocs: checkrst checkmd
+
+.PHONY: checkrst
+RST_FILES=$(shell find . -name '*.rst' | grep -v /vendor/ | sort)
+checkrst: $(RST_FILES)
+	@if [ "$(RSTCHECK)" == "" ]; then echo "Need rstcheck to lint RST files. Install rstcheck from your system package repository or from PyPI (https://pypi.org/project/rstcheck/)."; exit 1; fi
+	$(RSTCHECK) --report-level warning $^
+
+.PHONY: checkmd
+MD_FILES=$(shell find . -name '*.md' | grep -v /vendor/ | sort)
+checkmd: $(MD_FILES)
+	@if [ "$(MARKDOWNLINT)" == "" ]; then echo "Need markdownlint to lint RST files. Install markdownlint from your system package repository or from https://github.com/markdownlint/markdownlint."; exit 1; fi
+	$(MARKDOWNLINT) $^
+
 .PHONY: test
 test: vendor
 	gpg --import pgp/sops_functional_tests_key.asc 2>&1 1>/dev/null || exit 0