[PATCH v3 0/3] Add bblock documentation

Julien Stephan
2024-11-05T08:17:57Z

Hello,

The main purpose of this series is to add documentation for bblock.

bblock uses internally the 3 following variables: SIGGEN_LOCKEDSIGS,
SIGGEN_LOCKEDSIGS_TASKSIG_CHECK and SIGGEN_LOCKEDSIGS_TYPE which are not
documentated, so adding them to the glossary.

I also added "sstate" into the Yocto vocabulary to avoir error when running
Vale.

This series was built and checked with:

$ make html
$ make stylecheck VALEDOCS=dev-manual/bblock.rst
$ make sphinx-lint SPHINXLINTDOCS=dev-manual/bblock.rst

I tried my best to make Vale happy, but I still have the following
warnings:

dev-manual/bblock.rst
1:1 warning Try to keep the Coleman–Liau Index grade (10.29) below 9. Readability.ColemanLiau
1:1 warning Try to keep the Flesch reading ease score (57.51) above 70. Readability.FleschReadingEase
1:1 warning Try to keep the Flesch–Kincaid grade level (8.28) below 8. Readability.FleschKincaid
1:1 warning Try to keep the SMOG grade (11.42) below 10. Readability.SMOG
1:1 warning Try to keep the LIX score (38.20) below 35. Readability.LIX
3:1 suggestion Use sentence-style capitalization in 'Locking and Unlocking Recipes Using ******'. RedHat.Headings
29:49 suggestion Consider wrapping this Pascal or Camel case term ('TipsAndTricks') in backticks. RedHat.PascalCamelCase
39:60 suggestion Use simple language. Consider using 'many' rather than 'multiple'. RedHat.SimpleWords
39:60 warning 'multiple' is too wordy. write-good.TooWordy
57:62 warning 'multiple' is too wordy. write-good.TooWordy
76:43 error Use 'BitBake' instead of 'bitbake'. Vale.Terms
76:58 error Use 'OpenEmbedded' instead of 'openembedded'. Vale.Terms
76:71 warning Use either 'or' or 'and' in 'core/tree' RedHat.Slash
76:81 warning Use either 'or' or 'and' in 'meta/conf' RedHat.Slash
76:91 error Use 'BitBake' instead of 'bitbake'. Vale.Terms

About the Readability, I am not sure I can do better ^^ But anyone with
better english skills than me can help here!

About the capitalization: I decided to ignore it to keep consistency with
all other headings of the reference manual.

Suggestion and errors/warnings on lines 29 and 76 are false positive, we may need
to add some rule to ignore these check on :oe_git: directives
Also ignore the warning about 'multiple' as 'many' does not fit well in
this case.

Signed-off-by: Julien Stephan <jstephan@baylibre.com>
---
Changes in v3:
- Fix missing typos reported by Ulrich Olmann in v1
- Link to v2: https://lore.kernel.org/r/20241104-add-bblock-documentation-v2-0-0704e4d59929@baylibre.com

Changes in v2:
- Fixed various typos reported by Ulrich Ölmann and Antonin Godard
- Splited the series in two: the Readme/Makefile changes related to Vale
and SPHINXLINT and bblock documentation
- Added a bblock.conf file in `documentation/ref-manual/structure.rst`
- Link to v1: https://lore.kernel.org/r/20241031-add-bblock-documentation-v1-0-32b89093bbda@baylibre.com

---
Julien Stephan (3):
styles: vocabularies: Yocto: add sstate
ref-manual: variables: add SIGGEN_LOCKEDSIGS* variables
dev-manual: add bblock documentation

documentation/dev-manual/bblock.rst | 129 +++++++++++++++++++++
documentation/dev-manual/index.rst | 1 +
documentation/ref-manual/structure.rst | 8 ++
documentation/ref-manual/variables.rst | 47 ++++++++
.../styles/config/vocabularies/Yocto/accept.txt | 1 +
5 files changed, 186 insertions(+)
---
base-commit: 9563855ccd92e21fb6f8320c96a3a83e115c947e
change-id: 20241031-add-bblock-documentation-4a5f8cf9c6d2

Best regards,
--
Julien Stephan <jstephan@baylibre.com>