[PATCH 0/3] Add pre-commit support

[PATCH 0/3] Add pre-commit support

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (3):
      tools/check-glossaries: return 1 in case of failure
      tools/check-glossaries: fix default doc path
      Add a pre-commit hook to check the glossaries

 .pre-commit-config.yaml              |  8 ++++++++
 documentation/README                 | 10 ++++++++++
 documentation/tools/check-glossaries |  9 ++++++++-
 3 files changed, 26 insertions(+), 1 deletion(-)
---
base-commit: c518622d49c50844df230c8c2a8e08312104b7ad
change-id: 20260702-pre-commit-fe4d1ca7bbc4

[PATCH 1/3] tools/check-glossaries: return 1 in case of failure

[Antonin Godard]

Exit with 1 in case there's an issue with the glossaries. This will be
used in the next commit.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/check-glossaries | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/documentation/tools/check-glossaries b/documentation/tools/check-glossaries
index b5dfe834e..9f1a47126 100755
--- a/documentation/tools/check-glossaries
+++ b/documentation/tools/check-glossaries
@@ -4,6 +4,7 @@ import argparse
 import difflib
 import os
 import re
+import sys
 
 from pathlib import Path
 
@@ -33,6 +34,7 @@ def main():
     # :term:`A <ABIEXTENSION>` :term:`B` :term:`C <CACHE>`
     glossary_re = re.compile(r":term:`(?P<letter>[A-Z]{1})( <(?P<varname>[A-Z_]+)>)?`")
     entry_re = re.compile(r"^   :term:`(?P<entry>.+)`\s*$")
+    exit_code = 0
 
     for rst in glossaries:
 
@@ -74,6 +76,7 @@ def main():
         if diffs:
             print(f"WARNING: {rst}: entries are not properly sorted:")
             print('\n'.join(diffs))
+            exit_code = 1
 
         for letter in glossary:
             try:
@@ -81,9 +84,13 @@ def main():
             except ValueError:
                 print(f"WARNING: {rst}: variable "
                       f"{glossary[letter]} in glossary does not exist")
+                exit_code = 1
             if index > 0 and entries[index - 1].startswith(letter[0]):
                 print(f"WARNING: {rst}: The variable {glossary[letter]} shouldn't be in "
                      "the glossary.")
+                exit_code = 1
+
+    sys.exit(exit_code)
 
 
 if __name__ == "__main__":

-- 
2.54.0

Re: [docs] [PATCH 1/3] tools/check-glossaries: return 1 in case of failure

[Quentin Schulz]

Hi Antonin,

On 7/2/26 3:59 PM, Antonin Godard via lists.yoctoproject.org wrote:
> Exit with 1 in case there's an issue with the glossaries. This will be
> used in the next commit.
> 

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

[PATCH 2/3] tools/check-glossaries: fix default doc path

[Antonin Godard]

This default path pointing to the documentation was wrong, fix it.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/tools/check-glossaries | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/tools/check-glossaries b/documentation/tools/check-glossaries
index 9f1a47126..6bfddcfda 100755
--- a/documentation/tools/check-glossaries
+++ b/documentation/tools/check-glossaries
@@ -14,7 +14,7 @@ def parse_arguments() -> argparse.Namespace:
 
     parser.add_argument("-d", "--docs-dir",
                         type=Path,
-                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "documentation",
+                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "../",
                         help="Path to documentation/ directory in yocto-docs")
 
     return parser.parse_args()

-- 
2.54.0

Re: [docs] [PATCH 2/3] tools/check-glossaries: fix default doc path

[Quentin Schulz]

Hi Antonin,

On 7/2/26 3:59 PM, Antonin Godard via lists.yoctoproject.org wrote:
> This default path pointing to the documentation was wrong, fix it.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/tools/check-glossaries | 2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/documentation/tools/check-glossaries b/documentation/tools/check-glossaries
> index 9f1a47126..6bfddcfda 100755
> --- a/documentation/tools/check-glossaries
> +++ b/documentation/tools/check-glossaries
> @@ -14,7 +14,7 @@ def parse_arguments() -> argparse.Namespace:
>   
>       parser.add_argument("-d", "--docs-dir",
>                           type=Path,
> -                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "documentation",
> +                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "../",

Path(__file__).resolve().parent.parent

is much more readable IMO (and also, we avoid the mental gymnastic of 
seeing ../ and having to remove the last directory in the path.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 2/3] tools/check-glossaries: fix default doc path

[Antonin Godard]

Hi,

On Fri Jul 3, 2026 at 12:22 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 7/2/26 3:59 PM, Antonin Godard via lists.yoctoproject.org wrote:
>> This default path pointing to the documentation was wrong, fix it.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/tools/check-glossaries | 2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>> 
>> diff --git a/documentation/tools/check-glossaries b/documentation/tools/check-glossaries
>> index 9f1a47126..6bfddcfda 100755
>> --- a/documentation/tools/check-glossaries
>> +++ b/documentation/tools/check-glossaries
>> @@ -14,7 +14,7 @@ def parse_arguments() -> argparse.Namespace:
>>   
>>       parser.add_argument("-d", "--docs-dir",
>>                           type=Path,
>> -                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "documentation",
>> +                        default=Path(os.path.dirname(os.path.realpath(__file__))) / "../",
>
> Path(__file__).resolve().parent.parent
>
> is much more readable IMO (and also, we avoid the mental gymnastic of 
> seeing ../ and having to remove the last directory in the path.
>
> Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

True, we also don't need the os module with this anymore, thanks! v2 incoming.

Antonin

[PATCH 3/3] Add a pre-commit hook to check the glossaries

[Antonin Godard]

It is easy to badly order the glossaries or forget to update the list at
the beginning of the variables.rst file. Add a pre-commit hook that does
it for us, and update the README to mention to enable it.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 .pre-commit-config.yaml |  8 ++++++++
 documentation/README    | 10 ++++++++++
 2 files changed, 18 insertions(+)

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
new file mode 100644
index 000000000..f2b73a481
--- /dev/null
+++ b/.pre-commit-config.yaml
@@ -0,0 +1,8 @@
+repos:
+  - repo: local
+    hooks:
+      - id: check-glossaries
+        name: Check glossaries alphabetical order
+        entry: ./documentation/tools/check-glossaries
+        language: python
+        pass_filenames: false
diff --git a/documentation/README b/documentation/README
index 7c4472c73..326930932 100644
--- a/documentation/README
+++ b/documentation/README
@@ -89,6 +89,16 @@ generated with DocBook.
 How to build the Yocto Project documentation
 ============================================
 
+If possible, install pre-commit hooks to make sure you did not miss any
+updates that are run automatically:
+
+  $ pre-commit install
+
+The pre-commit project can be installed on your host using your package manager,
+usually under the name "pre-commit", e.g.:
+
+  $ sudo apt-get install pre-commit
+
 To build the documentation, you need Sphinx and a few other packages,
 which depend on your host GNU/Linux distribution. Such packages are listed on
 https://docs.yoctoproject.org/dev/ref-manual/system-requirements.html#required-packages-for-the-build-host

-- 
2.54.0

Re: [docs] [PATCH 3/3] Add a pre-commit hook to check the glossaries

[Quentin Schulz]

Hi Antonin,

On 7/2/26 3:59 PM, Antonin Godard via lists.yoctoproject.org wrote:
> It is easy to badly order the glossaries or forget to update the list at
> the beginning of the variables.rst file. Add a pre-commit hook that does
> it for us, and update the README to mention to enable it.
> 

Tested-by: Quentin Schulz <quentin.schulz@cherry.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

I think the check-glossaries messages need to be reworded because I had 
to read the script to understand what the messages meant and what I was 
supposed to do to fix them. Will send follow-up patches.

Thanks,
Quentin