[PATCH v2 0/3] Add pre-commit support

[PATCH v2 0/3] Add pre-commit support

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Changes in v2:
- Patch 2/3: apply default path suggestion from Quentin (thanks!)
- Link to v1: https://patch.msgid.link/20260702-pre-commit-v1-0-0ebd211b5d5e@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 | 10 ++++++++--
 3 files changed, 26 insertions(+), 2 deletions(-)
---
base-commit: def10b40398732ff73f23bf9cb8c0288a8ad7640
change-id: 20260702-pre-commit-fe4d1ca7bbc4

[PATCH v2 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 for pre-commit support.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
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

[PATCH v2 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 | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/documentation/tools/check-glossaries b/documentation/tools/check-glossaries
index 9f1a47126..da4987ff3 100755
--- a/documentation/tools/check-glossaries
+++ b/documentation/tools/check-glossaries
@@ -2,7 +2,6 @@
 
 import argparse
 import difflib
-import os
 import re
 import sys
 
@@ -14,7 +13,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(__file__).resolve().parent.parent,
                         help="Path to documentation/ directory in yocto-docs")
 
     return parser.parse_args()

-- 
2.54.0

[PATCH v2 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.

Tested-by: Quentin Schulz <quentin.schulz@cherry.de>
Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
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 v2 2/3] tools/check-glossaries: fix default doc path

[Quentin Schulz]

Hi Antonin,

On 7/3/26 1:31 PM, Antonin Godard via lists.yoctoproject.org wrote:
> This default path pointing to the documentation was wrong, fix it.
> 

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

Thanks!
Quentin