[kirkstone][PATCH 1/9] manuals: add initial stylechecks with Vale

michael.opdenacker
2024-03-25T13:27:52Z

Use the "Vale" (https://vale.sh) tool to perform text style checks
Run "make stylecheck" to run the checks.

This just checks the text, not the Sphinx syntax style choices.

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Suggested-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
---
documentation/.gitignore | 2 ++
documentation/.vale.ini | 7 +++++++
documentation/Makefile | 13 ++++++++++++-
documentation/README | 14 ++++++++++++++
documentation/standards.md | 15 +++++++++++++++
.../config/vocabularies/OpenSource/accept.txt | 4 ++++
.../styles/config/vocabularies/Yocto/accept.txt | 4 ++++
7 files changed, 58 insertions(+), 1 deletion(-)
create mode 100644 documentation/.vale.ini
create mode 100644 documentation/styles/config/vocabularies/OpenSource/accept.txt
create mode 100644 documentation/styles/config/vocabularies/Yocto/accept.txt

diff --git a/documentation/.gitignore b/documentation/.gitignore
index 096b97ec28..a8f86f7c98 100644
--- a/documentation/.gitignore
+++ b/documentation/.gitignore
@@ -5,3 +5,5 @@ sphinx-static/switchers.js
.vscode/
*/svg/*.png
*/svg/*.pdf
+styles/*
+!styles/config
diff --git a/documentation/.vale.ini b/documentation/.vale.ini
new file mode 100644
index 0000000000..02042bb632
--- /dev/null
+++ b/documentation/.vale.ini
@@ -0,0 +1,7 @@
+StylesPath = styles
+MinAlertLevel = suggestion
+Packages = RedHat, proselint, write-good, alex, Readability, Joblint
+Vocab = Yocto, OpenSource
+[*.rst]
+BasedOnStyles = Vale, RedHat, proselint, write-good, alex, Readability, Joblint
+
diff --git a/documentation/Makefile b/documentation/Makefile
index 33bbca0bab..e5f0effeb5 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -5,6 +5,9 @@
# from the environment for the first two.
SPHINXOPTS ?= -W --keep-going -j auto
SPHINXBUILD ?= sphinx-build
+# Release notes are excluded because they contain contributor names and commit messages which can't be modified
+VALEOPTS ?= --no-wrap --glob '!migration-guides/release-notes-*.rst'
+VALEDOCS ?= .
SOURCEDIR = .
IMAGEDIRS = */svg
BUILDDIR = _build
@@ -20,7 +23,7 @@ endif
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

-.PHONY: all help Makefile clean publish epub latexpdf
+.PHONY: all help Makefile clean stylecheck publish epub latexpdf

publish: Makefile html singlehtml
rm -rf $(BUILDDIR)/$(DESTDIR)/
@@ -46,6 +49,14 @@ PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCED
clean:
@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js

+stylecheck:
+ vale sync
+ vale $(VALEOPTS) $(VALEDOCS)
+
+stylecheck:
+ vale sync
+ vale $(VALEOPTS) $(VALEDOCS)
+
epub: $(PNGs)
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

diff --git a/documentation/README b/documentation/README
index 4d31036e69..8035418cac 100644
--- a/documentation/README
+++ b/documentation/README
@@ -151,6 +151,20 @@ dependencies in a virtual environment:
$ pipenv install
$ pipenv run make html

+Style checking the Yocto Project documentation
+==============================================
+
+The project is starting to use Vale (https://vale.sh/)
+to validate the text style.
+
+To install Vale:
+
+ $ pip install vale
+
+To run Vale:
+
+ $ make stylecheck
+
Sphinx theme and CSS customization
==================================

diff --git a/documentation/standards.md b/documentation/standards.md
index a2274f6d6e..d3b25adfab 100644
--- a/documentation/standards.md
+++ b/documentation/standards.md
@@ -5,6 +5,21 @@ documentation is created.

It is currently a work in progress.

+## Automatic style validation
+
+There is an ongoing effort to automate style validation
+through the [Vale](https://vale.sh/). To try it, run:
+
+ $ make stylecheck
+
+Note that this just applies to text. Therefore, the syntax
+conventions described below still apply.
+
+If you wish to add a new word to an "accept.txt" file
+(./styles/config/vocabularies/<Vocab>/accept.txt),
+make sure the spelling and capitalization matches
+what Wikipedia or the project defining this word uses.
+
## Text standards

This section has not been filled yet
diff --git a/documentation/styles/config/vocabularies/OpenSource/accept.txt b/documentation/styles/config/vocabularies/OpenSource/accept.txt
new file mode 100644
index 0000000000..98e76ae1f5
--- /dev/null
+++ b/documentation/styles/config/vocabularies/OpenSource/accept.txt
@@ -0,0 +1,4 @@
+ftrace
+toolchain
+systemd
+LTTng
diff --git a/documentation/styles/config/vocabularies/Yocto/accept.txt b/documentation/styles/config/vocabularies/Yocto/accept.txt
new file mode 100644
index 0000000000..b725414014
--- /dev/null
+++ b/documentation/styles/config/vocabularies/Yocto/accept.txt
@@ -0,0 +1,4 @@
+Yocto
+BSP
+BitBake
+OpenEmbedded
--
2.34.1