| Message ID | 20240312210345.8832-1-michael.opdenacker@bootlin.com |
|---|---|
| State | New |
| Headers | show |
| Series | manuals: add initial stylechecks with Vale | expand |
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
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.
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
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.
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