From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>,
Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Subject: [kirkstone][PATCH 1/9] manuals: add initial stylechecks with Vale
Date: Mon, 25 Mar 2024 14:27:29 +0100 [thread overview]
Message-ID: <20240325132737.3018073-2-michael.opdenacker@bootlin.com> (raw)
In-Reply-To: <20240325132737.3018073-1-michael.opdenacker@bootlin.com>
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>
---
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
next prev parent reply other threads:[~2024-03-25 13:27 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-25 13:27 [kirkstone][PATCH 0/9] documentation backports michael.opdenacker
2024-03-25 13:27 ` michael.opdenacker [this message]
2024-03-25 13:27 ` [kirkstone][PATCH 2/9] profile-manual: usage.rst: formatting fixes michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 3/9] manuals: use "manual page(s)" michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 4/9] profile-manual: usage.rst: fix reference to bug report michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 5/9] migration-guides: add release notes for 4.0.17 michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 6/9] contributor-guide: be more specific about meta-* trees michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 7/9] profile-manual: usage.rst: further style improvements michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 8/9] ref-manual: add documentation of the variable SPDX_NAMESPACE_PREFIX michael.opdenacker
2024-03-25 13:27 ` [kirkstone][PATCH 9/9] dev-manual: improve descriptions of 'bitbake -S printdiff' 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=20240325132737.3018073-2-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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.