* [PATCH] manuals: add initial stylechecks with Vale
@ 2024-03-12 21:03 michael.opdenacker
2024-03-13 9:42 ` [docs] " Quentin Schulz
0 siblings, 1 reply; 6+ messages in thread
From: michael.opdenacker @ 2024-03-12 21:03 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker, Thomas Petazzoni
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [docs] [PATCH] manuals: add initial stylechecks with Vale
2024-03-12 21:03 [PATCH] manuals: add initial stylechecks with Vale michael.opdenacker
@ 2024-03-13 9:42 ` Quentin Schulz
2024-03-13 14:55 ` Michael Opdenacker
0 siblings, 1 reply; 6+ messages in thread
From: Quentin Schulz @ 2024-03-13 9:42 UTC (permalink / raw)
To: michael.opdenacker, Michael Opdenacker via lists.yoctoproject.org,
docs
Cc: Michael Opdenacker, Thomas Petazzoni
Hi Michael,
On March 12, 2024 10:03:45 PM GMT+01:00, "Michael Opdenacker via lists.yoctoproject.org" <michael.opdenacker=bootlin.com@lists.yoctoproject.org> wrote:
>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.
This is an article that requires subscription to LWN unfortunately.
>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'
Do we really need `--no-wrap` twice here?
[...]
>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
>+
Isn't this supposed to be `make stylecheck` here?
>+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
Are those strings matched even when they are highlighted with simple/double tick quotes? If not, that could be a way to not have to expand this list too often and also it's nice to highlight the name of pieces of SW (well, excluding toolchain from my remark obviously).
Cheers,
Quentin
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [docs] [PATCH] manuals: add initial stylechecks with Vale
2024-03-13 9:42 ` [docs] " Quentin Schulz
@ 2024-03-13 14:55 ` Michael Opdenacker
2024-03-13 15:09 ` Quentin Schulz
0 siblings, 1 reply; 6+ messages in thread
From: Michael Opdenacker @ 2024-03-13 14:55 UTC (permalink / raw)
To: Quentin Schulz; +Cc: Thomas Petazzoni, docs
Hi Quentin
I was sure the topic would interest you! Thanks for the review.
On 3/13/24 at 10:42, Quentin Schulz wrote:
> Hi Michael,
>
> On March 12, 2024 10:03:45 PM GMT+01:00, "Michael Opdenacker via lists.yoctoproject.org" <michael.opdenacker=bootlin.com@lists.yoctoproject.org> wrote:
>> 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.
> This is an article that requires subscription to LWN unfortunately.
Ouch, sorry for the oversight. We just have to wait until the article is
open to everyone.
>
>> 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'
> Do we really need `--no-wrap` twice here?
Oops, fixed.
>
> [...]
>
>> 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
>> +
> Isn't this supposed to be `make stylecheck` here?
Oops, fixed too.
>
>> +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
> Are those strings matched even when they are highlighted with simple/double tick quotes? If not, that could be a way to not have to expand this list too often and also it's nice to highlight the name of pieces of SW (well, excluding toolchain from my remark obviously).
I've just checked by adding a typo, like "Yotco", and found out that:
- ``Yotco`` is not reported
- But "Yotco" is
So, yes, using "``" allows to write any string we want, and the tool
won't check such strings. So, this avoids lots of false positives and
this can actually help to locate instances when such double quotes are
missing!
An issue though. If I add "Yotco" to one of the variable definitions in
ref-manual/variables.rst, the typo remains unnoticed! Adding this to my
issue list...
Cheers
Michael.
--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [docs] [PATCH] manuals: add initial stylechecks with Vale
2024-03-13 14:55 ` Michael Opdenacker
@ 2024-03-13 15:09 ` Quentin Schulz
2024-03-13 15:22 ` Michael Opdenacker
0 siblings, 1 reply; 6+ messages in thread
From: Quentin Schulz @ 2024-03-13 15:09 UTC (permalink / raw)
To: michael.opdenacker, Quentin Schulz; +Cc: Thomas Petazzoni, docs
Hi Michael,
On 3/13/24 15:55, Michael Opdenacker via lists.yoctoproject.org wrote:
> Hi Quentin
>
> I was sure the topic would interest you! Thanks for the review.
>
It is actually a quite interesting timing, I myself was vaguely looking
for linters for our user manuals yesterday.
So I can say I found the following:
- sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint). This
mainly complained about tabs being used, but maybe it would find some
interesting things in the YP docs?
- sphinxawesome-codelinter
(https://github.com/kai687/sphinxawesome-codelinter). This is to run a
specific command for snippets inside code blocks with an assigned
language. This will be useful to us because we wrote quite a lot of
shell scripts in our user manual so having shellcheck run on those will
be nice :) For YP/OE though... not sure. I think there's oelint-adv we
could use?
[...]
>>> 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
>> Are those strings matched even when they are highlighted with
>> simple/double tick quotes? If not, that could be a way to not have to
>> expand this list too often and also it's nice to highlight the name of
>> pieces of SW (well, excluding toolchain from my remark obviously).
>
>
> I've just checked by adding a typo, like "Yotco", and found out that:
>
> - ``Yotco`` is not reported
>
> - But "Yotco" is
>
> So, yes, using "``" allows to write any string we want, and the tool
> won't check such strings. So, this avoids lots of false positives and
> this can actually help to locate instances when such double quotes are
> missing!
>
Thanks for checking!
That was the idea behind my question :) Nice to hear (though.... who's
going to check for typos inside those single ticks now :D?).
Cheers,
Quentin
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [docs] [PATCH] manuals: add initial stylechecks with Vale
2024-03-13 15:09 ` Quentin Schulz
@ 2024-03-13 15:22 ` Michael Opdenacker
0 siblings, 0 replies; 6+ messages in thread
From: Michael Opdenacker @ 2024-03-13 15:22 UTC (permalink / raw)
To: Quentin Schulz, Quentin Schulz; +Cc: Thomas Petazzoni, docs
Hi Quentin,
On 3/13/24 at 16:09, Quentin Schulz wrote:
>
> So I can say I found the following:
> - sphinx-lint (https://github.com/sphinx-contrib/sphinx-lint). This
> mainly complained about tabs being used, but maybe it would find some
> interesting things in the YP docs?
Thanks for sharing. This one may indeed be interesting to enforce our
"syntax style" preferences.
My time is limited at the moment, but don't hesitate to try it
by yourself on the Yocto docs too.
Cheers
Michael.
--
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH] manuals: add initial stylechecks with Vale
@ 2024-03-13 9:29 michael.opdenacker
0 siblings, 0 replies; 6+ messages in thread
From: michael.opdenacker @ 2024-03-13 9:29 UTC (permalink / raw)
To: docs; +Cc: Michael Opdenacker, Thomas Petazzoni
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!
Changes in V2:
- Replace "vale init" (wrong) by "vale sync"
to get download the latest versions of the style files
---
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..e9ea792363 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 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..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
^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2024-03-13 15:23 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-03-12 21:03 [PATCH] manuals: add initial stylechecks with Vale michael.opdenacker
2024-03-13 9:42 ` [docs] " 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
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox