From: michael.opdenacker@bootlin.com
To: docs@lists.yoctoproject.org
Cc: Michael Opdenacker <michael.opdenacker@bootlin.com>,
Thomas Petazzoni <thomas.petazzoni@bootlin.com>
Subject: [nanbield][PATCH 01/11] manuals: add initial stylechecks with Vale
Date: Mon, 25 Mar 2024 14:29:16 +0100 [thread overview]
Message-ID: <20240325132926.3018186-2-michael.opdenacker@bootlin.com> (raw)
In-Reply-To: <20240325132926.3018186-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 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..804a7dd94c 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)
$(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..e0c0cba83c 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
### 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 prev parent reply other threads:[~2024-03-25 13:29 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-25 13:29 [nanbield][PATCH 00/11] documentation backports michael.opdenacker
2024-03-25 13:29 ` michael.opdenacker [this message]
2024-03-25 13:29 ` [nanbield][PATCH 02/11] profile-manual: usage.rst: formatting fixes michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 03/11] manuals: use "manual page(s)" michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 04/11] profile-manual: usage.rst: fix reference to bug report michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 05/11] documentation: Makefile: remove releases.rst in "make clean" michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 06/11] migration-guides: add release notes for 4.0.17 michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 07/11] contributor-guide: be more specific about meta-* trees michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 08/11] profile-manual: usage.rst: further style improvements michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 09/11] ref-manual: add documentation of the variable SPDX_NAMESPACE_PREFIX michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 10/11] sdk-manual: correctly describe separate build-sysroots tasks in direct sdk workflows michael.opdenacker
2024-03-25 13:29 ` [nanbield][PATCH 11/11] 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=20240325132926.3018186-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.