From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>,
Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Subject: [PATCH] manuals: add initial stylechecks with Vale
Date: Tue, 12 Mar 2024 22:03:45 +0100 [thread overview]
Message-ID: <20240312210345.8832-1-michael.opdenacker@bootlin.com> (raw)
From: Michael Opdenacker <michael.opdenacker@bootlin.com>
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>
---
See https://lwn.net/Articles/964075/ for a recent introduction.
Don't hesitate to run the checks, propose fixes for the reported
issues and improvements to the checking rules and accepted words!
---
documentation/.gitignore | 2 ++
documentation/.vale.ini | 7 +++++++
documentation/Makefile | 9 ++++++++-
documentation/README | 14 ++++++++++++++
documentation/standards.md | 15 +++++++++++++++
.../config/vocabularies/OpenSource/accept.txt | 4 ++++
.../styles/config/vocabularies/Yocto/accept.txt | 4 ++++
7 files changed, 54 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 494b4f4de5..b23d598054 100644
--- a/documentation/.gitignore
+++ b/documentation/.gitignore
@@ -7,3 +7,5 @@ releases.rst
.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 9fb6814c8f..e1b61f17f1 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 --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,10 @@ PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCED
clean:
@rm -rf $(BUILDDIR) $(PNGs) $(PDFs) poky.yaml sphinx-static/switchers.js
+stylecheck:
+ vale init
+ vale $(VALEOPTS) $(VALEDOCS)
+
epub: $(PNGs)
$(SOURCEDIR)/set_versions.py
@$(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 9f4771ebd9..a4f8be0dcf 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 vale
+
+Note that this just applies to text. Therefore, the syntax
+conventions described below still apply.
+
+If you wish to add words to the "accept.txt" files
+(./styles/config/vocabularies/<Vocab>/accept.txt),
+make sure the spelling and capitalization matches
+what Wikipedia uses. Wikipedia is our reference!
+
## Text standards
### Bulleted lists
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
next reply other threads:[~2024-03-12 21:03 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-12 21:03 michael.opdenacker [this message]
2024-03-13 9:42 ` [docs] [PATCH] manuals: add initial stylechecks with Vale Quentin Schulz
2024-03-13 14:55 ` Michael Opdenacker
2024-03-13 15:09 ` Quentin Schulz
2024-03-13 15:22 ` Michael Opdenacker
-- strict thread matches above, loose matches on Subject: below --
2024-03-13 9:29 michael.opdenacker
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240312210345.8832-1-michael.opdenacker@bootlin.com \
--to=michael.opdenacker@bootlin.com \
--cc=docs@lists.yoctoproject.org \
--cc=thomas.petazzoni@bootlin.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).