Add pre-commit support
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
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
@@ -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
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
PATCH 2/3 tools/check-glossaries: fix default doc path
In reply to Antonin GodardThis 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
@@ -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
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.
Signed-off-by Antonin Godard <[email protected]>--- documentation/tools/check-glossaries | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)documentation/tools/check-glossaries +0
-0
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
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.
Signed-off-by Antonin Godard <[email protected]>--- documentation/tools/check-glossaries | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)documentation/tools/check-glossaries +0
-0documentation/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.
Reviewed-by Quentin Schulz <[email protected]>
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
In reply to Antonin GodardIt 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
@@ -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
@@ -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
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.rstfile. 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