mbox series

[v5,0/3] Add bblock documentation

Message ID 20241106-add-bblock-documentation-v5-0-625806c6a3ce@baylibre.com
Headers show
Series Add bblock documentation | expand

Message

Julien Stephan Nov. 6, 2024, 1:54 p.m. UTC 
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 v5:
- add missing "tmp" in stamps file path in SIGGEN_LOCKEDSIGS
  documentation
- reword a sentence in SIGGEN_LOCKEDSIGS  documentation
- Link to v4: https://lore.kernel.org/r/20241106-add-bblock-documentation-v4-0-9f24dfe69243@baylibre.com

Changes in v4:
- use "the sstate cache" everywhere for consistency
- fix some typo
- add comment to explain that bblock.conf does not exist by default
- Link to v3: https://lore.kernel.org/r/20241105-add-bblock-documentation-v3-0-b870ded39a2d@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             |   9 ++
 documentation/ref-manual/variables.rst             |  47 ++++++++
 .../styles/config/vocabularies/Yocto/accept.txt    |   1 +
 5 files changed, 187 insertions(+)
---
base-commit: 7b40c7b73a360a1ec383c4c9f00c3e126208320b
change-id: 20241031-add-bblock-documentation-4a5f8cf9c6d2

Best regards,

Comments

Antonin Godard Nov. 6, 2024, 3:28 p.m. UTC | #1 
Hi Julien,

On Wed Nov 6, 2024 at 2:54 PM CET, Julien Stephan wrote:
> 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 v5:
> - add missing "tmp" in stamps file path in SIGGEN_LOCKEDSIGS
>   documentation
> - reword a sentence in SIGGEN_LOCKEDSIGS  documentation
> - Link to v4: https://lore.kernel.org/r/20241106-add-bblock-documentation-v4-0-9f24dfe69243@baylibre.com
>
> Changes in v4:
> - use "the sstate cache" everywhere for consistency
> - fix some typo
> - add comment to explain that bblock.conf does not exist by default
> - Link to v3: https://lore.kernel.org/r/20241105-add-bblock-documentation-v3-0-b870ded39a2d@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             |   9 ++
>  documentation/ref-manual/variables.rst             |  47 ++++++++
>  .../styles/config/vocabularies/Yocto/accept.txt    |   1 +
>  5 files changed, 187 insertions(+)
> ---
> base-commit: 7b40c7b73a360a1ec383c4c9f00c3e126208320b
> change-id: 20241031-add-bblock-documentation-4a5f8cf9c6d2
>
> Best regards,

This looks good to me, for the series:

Reviewed-by: Antonin Godard <antonin.godard@bootlin.com>

Thanks a lot!
Antonin
Antonin Godard Nov. 6, 2024, 5:32 p.m. UTC | #2 
From: Antonin Godard <antonin.godard@bootlin.com>


On Wed, 06 Nov 2024 14:54:44 +0100, Julien Stephan wrote:
> 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.
> 
> [...]

Applied, thanks!

[1/5] documentation: Makefile: add SPHINXLINTDOCS to specify subset to sphinx-lint
      commit: 3dfe7b5c746af31de74f67cf88214e5d52bdb65d
[2/5] README: add instruction to run Vale on a subset
      commit: 262237f72534c983e178231cb6839ed69709c443
[3/5] styles: vocabularies: Yocto: add sstate
      commit: 1c50726296e876747ea3f862729e953f025ce619
[4/5] ref-manual: variables: add SIGGEN_LOCKEDSIGS* variables
      commit: 32e3995bed2836f549866ec3b8ad254bdda37dbf
[5/5] dev-manual: add bblock documentation
      commit: a082aa39840587d3af6c3f4a2c2747564ca37414

Best regards,