Skip to contentSkip to conversation

Add pre-commit support

PATCH Superseded Antonin Godard 2 participants 8 messages Jul 2 – Jul 3

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover Add pre-commit support

---
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

#1 lore raw

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

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

---
 documentation/tools/check-glossaries | 7 +++++++
 1 file changed, 7 insertions(+)
documentation/tools/check-glossaries +7 -0
index b5dfe834e..9f1a47126 100755
@@ -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__":
Signature · 1 line
2.54.0
Reviewed-by on v1 1/3
#2 lore raw

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

Hi Antonin,

Quoted 3 lines · Antonin Godard via lists.yoctoproject.org

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

Thanks!
Quentin

#3 lore raw

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

In reply to Antonin Godard

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

---
 documentation/tools/check-glossaries | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
documentation/tools/check-glossaries +1 -1
index 9f1a47126..6bfddcfda 100755
@@ -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()
Signature · 1 line
2.54.0
Reviewed-by on v1 2/3
#4 lore raw

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

Hi Antonin,

Quoted 12 lines · Antonin Godard via lists.yoctoproject.org

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

---
  documentation/tools/check-glossaries | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
documentation/tools/check-glossaries +0 -0
index 9f1a47126..6bfddcfda 100755

documentation/tools/check-glossaries def parse_arguments() -> argparse.Namespace: · line 17

Quoted 5 lines
documentation/tools/check-glossaries +1 -1
@@ -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.

Thanks!
Quentin

#5 lore raw

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

Hi,

Quoted 23 lines · Quentin Schulz

Hi Antonin,

Quoted 12 lines · Antonin Godard via lists.yoctoproject.org

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

---
  documentation/tools/check-glossaries | 2 +-
  1 file changed, 1 insertion(+), 1 deletion(-)
documentation/tools/check-glossaries +0 -0
index 9f1a47126..6bfddcfda 100755

documentation/tools/check-glossaries def parse_arguments() -> argparse.Namespace: · line 17

Quoted 5 lines
documentation/tools/check-glossaries +1 -1
@@ -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

Quoted 4 lines

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

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

Antonin

#6 lore raw

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

In reply to 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.

---
 .pre-commit-config.yaml |  8 ++++++++
 documentation/README    | 10 ++++++++++
 2 files changed, 18 insertions(+)
.pre-commit-config.yaml new file +8 -0
new file mode 100644
index 000000000..f2b73a481
@@ -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
documentation/README +10 -0
index 7c4472c73..326930932 100644
@@ -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
Signature · 1 line
2.54.0
Tested-by Reviewed-by on v1 3/3
#7 lore raw

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

Hi Antonin,

Quoted 4 lines · Antonin Godard via lists.yoctoproject.org

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.

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