diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 000000000..fc3916fe0 --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 885e14376..947dcfd48 100644 --- a/CONTRIBUTING.md +++ b/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: diff --git a/Makefile b/Makefile index a8e417941..d0e22c059 100644 --- a/Makefile +++ b/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