286 lines
8.9 KiB
Python
286 lines
8.9 KiB
Python
#!/usr/bin/env python3
|
||
# SPDX-License-Identifier: MIT
|
||
|
||
"""
|
||
A Python script to add or update the "See also" section for all translations of a page.
|
||
|
||
Note: If the current directory or one of its parents is called "tldr", the script will assume it is the tldr root, i.e., the directory that contains a clone of https://github.com/tldr-pages/tldr
|
||
If the script doesn't find it in the current path, the environment variable TLDR_ROOT will be used as the tldr root. Also, ensure 'git' is available.
|
||
|
||
Usage:
|
||
python3 scripts/set-see-also.py [-p PAGE] [-S] [-l LANGUAGE] [-s] [-n] [COMMANDS...]
|
||
|
||
Options:
|
||
-p, --page PAGE
|
||
Specify the page in the format "platform/command". This option allows setting the link for a specific page.
|
||
-S, --sync
|
||
Synchronize each translation's "See also" section (if exists) with that of the English page.
|
||
-l, --language LANGUAGE
|
||
Specify the language, a POSIX Locale Name in the form of "ll" or "ll_CC" (e.g. "fr" or "pt_BR").
|
||
-s, --stage
|
||
Stage modified pages (requires 'git' on $PATH and TLDR_ROOT to be a Git repository).
|
||
-n, --dry-run
|
||
Show what changes would be made without actually modifying the page.
|
||
|
||
Positional Argument:
|
||
COMMANDS The commands to be set in the "See also" section.
|
||
|
||
Examples:
|
||
1. Set the commands for a specific page:
|
||
python3 scripts/set-see-also.py -p common/bash zsh,!
|
||
python3 scripts/set-see-also.py --page common/bash zsh,!
|
||
|
||
2. Read English pages and synchronize the "See also" section across translations:
|
||
python3 scripts/set-see-also.py -S
|
||
python3 scripts/set-see-also.py --sync
|
||
|
||
3. Read English pages and synchronize the "See also" section for Brazilian Portuguese pages only:
|
||
python3 scripts/set-see-also.py -S -l pt_BR
|
||
python3 scripts/set-see-also.py --sync --language pt_BR
|
||
|
||
4. Read English pages, synchronize the "See also" section across translations and stage modified pages for commit:
|
||
python3 scripts/set-see-also.py -Ss
|
||
python3 scripts/set-see-also.py --sync --stage
|
||
|
||
5. Show what changes would be made across translations:
|
||
python3 scripts/set-see-also.py -Sn
|
||
python3 scripts/set-see-also.py --sync --dry-run
|
||
"""
|
||
|
||
import re
|
||
import sys
|
||
from pathlib import Path
|
||
from dataclasses import dataclass
|
||
from _common import (
|
||
IGNORE_FILES,
|
||
Colors,
|
||
get_tldr_root,
|
||
get_templates,
|
||
get_pages_dirs,
|
||
get_target_paths,
|
||
get_locale,
|
||
get_status,
|
||
stage,
|
||
create_colored_line,
|
||
create_argument_parser,
|
||
)
|
||
|
||
|
||
@dataclass
|
||
class Config:
|
||
"""Global configuration for the script"""
|
||
|
||
root: Path
|
||
pages_dirs: list[Path]
|
||
templates: dict[str, str]
|
||
dry_run: bool = False
|
||
language: str = ""
|
||
|
||
|
||
def set_see_also(
|
||
path: Path, see_also: str, dry_run: bool = False, language_to_update: str = ""
|
||
) -> str:
|
||
"""
|
||
Write a "See also" section in a page to disk.
|
||
|
||
Parameters:
|
||
path (string): Path to a page
|
||
see_also (string): The "See also" section to insert.
|
||
dry_run (bool): Whether to perform a dry-run, i.e. only show the changes that would be made.
|
||
language_to_update (string): Optionally, the language of the translation to be updated.
|
||
|
||
Returns:
|
||
str: Execution status
|
||
"" if the page does not need an update or if the locale does not match language_to_update.
|
||
"\x1b[36msee also added"
|
||
"\x1b[34msee also updated"
|
||
"\x1b[36msee also would be added"
|
||
"\x1b[34msee also would be updated"
|
||
"""
|
||
|
||
locale = get_locale(path)
|
||
if locale not in config.templates or (
|
||
language_to_update != "" and locale != language_to_update
|
||
):
|
||
# return empty status to indicate that no changes were made
|
||
return ""
|
||
|
||
with path.open(encoding="utf-8") as f:
|
||
lines = f.readlines()
|
||
|
||
desc_start = 0
|
||
desc_end = 0
|
||
|
||
# find start and end of description
|
||
for i, line in enumerate(lines):
|
||
if line.startswith(">") and desc_start == 0:
|
||
desc_start = i
|
||
if not lines[i + 1].startswith(">") and desc_start != 0:
|
||
desc_end = i
|
||
break
|
||
|
||
new_line = config.templates[locale].replace("`example`", see_also)
|
||
|
||
if lines[desc_end - 1] == new_line:
|
||
# return empty status to indicate that no changes were made
|
||
return ""
|
||
|
||
if re.search(r"^>.*[：:]\s*`", lines[desc_end - 1]):
|
||
# overwrite second last line
|
||
lines[desc_end - 1] = new_line
|
||
action = "updated"
|
||
else:
|
||
# add new line
|
||
lines.insert(desc_end, new_line)
|
||
action = "added"
|
||
|
||
status = get_status(action, dry_run, "see also")
|
||
|
||
if not dry_run: # Only write to the path during a non-dry-run
|
||
with path.open("w", encoding="utf-8") as f:
|
||
f.writelines(lines)
|
||
|
||
return status
|
||
|
||
|
||
def get_see_also(path: Path) -> str:
|
||
"""
|
||
Determine whether the given path has a "See also" section.
|
||
|
||
Parameters:
|
||
path (Path): Path to a page
|
||
|
||
Returns:
|
||
str: "" If the path doesn't exit or does not have a link,
|
||
otherwise return the "See also" section.
|
||
"""
|
||
|
||
if not path.exists():
|
||
return ""
|
||
with path.open(encoding="utf-8") as f:
|
||
lines = f.readlines()
|
||
|
||
desc_start = 0
|
||
desc_end = 0
|
||
|
||
# find start and end of description
|
||
for i, line in enumerate(lines):
|
||
if line.startswith(">") and desc_start == 0:
|
||
desc_start = i
|
||
if not lines[i + 1].startswith(">") and desc_start != 0:
|
||
desc_end = i
|
||
break
|
||
|
||
candidate = lines[desc_end - 1]
|
||
|
||
if not re.match(r"^> See also:", candidate):
|
||
return ""
|
||
|
||
commands = re.findall(r"`([^`]+)`", candidate)
|
||
if not commands:
|
||
return ""
|
||
|
||
# Normalise spacing and output format used by your template
|
||
return ", ".join(f"`{command.strip()}`" for command in commands)
|
||
|
||
|
||
def sync(
|
||
root: Path,
|
||
pages_dirs: list[Path],
|
||
command: str,
|
||
see_also: str,
|
||
dry_run: bool = False,
|
||
language_to_update: str = "",
|
||
) -> list[Path]:
|
||
"""
|
||
Synchronize a "See also" section into all translations.
|
||
|
||
Parameters:
|
||
root (Path): TLDR_ROOT
|
||
pages_dirs (list of Path's): Path's of page entry and platform, e.g. "page.fr/common".
|
||
command (str): A command like "tar".
|
||
see_also (str): A "See also" section like "gtar".
|
||
dry_run (bool): Whether to perform a dry-run, i.e. only show the changes that would be made.
|
||
language_to_update (str): Optionally, the language of the translation to be updated.
|
||
|
||
Returns:
|
||
list (list of Path's): A list of Path's to be staged into git, using by --stage option.
|
||
"""
|
||
paths = []
|
||
for page_dir in pages_dirs:
|
||
path = root / page_dir / command
|
||
if path.exists():
|
||
status = set_see_also(path, see_also, dry_run, language_to_update)
|
||
if status != "":
|
||
rel_path = "/".join(path.parts[-3:])
|
||
paths.append(rel_path)
|
||
print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
|
||
return paths
|
||
|
||
|
||
def main():
|
||
parser = create_argument_parser(
|
||
'Sets the "See also" section for all translations of a page'
|
||
)
|
||
parser.add_argument("see_also", type=str, nargs="?", default="")
|
||
args = parser.parse_args()
|
||
|
||
# Print usage information if no arguments were provided
|
||
if len(sys.argv) == 1:
|
||
parser.print_help()
|
||
return
|
||
|
||
root = get_tldr_root()
|
||
pages_dirs = get_pages_dirs(root)
|
||
templates = get_templates(root, "see-also-mentions.md")
|
||
|
||
global config
|
||
config = Config(
|
||
root=root,
|
||
pages_dirs=pages_dirs,
|
||
templates=templates,
|
||
dry_run=args.dry_run,
|
||
language=args.language,
|
||
)
|
||
|
||
target_paths = []
|
||
|
||
# Use '--page' option
|
||
if args.page != "":
|
||
target_paths += get_target_paths(args.page, pages_dirs)
|
||
|
||
args.see_also = ", ".join(f"`{p}`" for p in args.see_also.split(","))
|
||
|
||
for path in target_paths:
|
||
rel_path = "/".join(path.parts[-3:])
|
||
status = set_see_also(path, args.see_also, args.dry_run, args.language)
|
||
if status != "":
|
||
print(create_colored_line(Colors.GREEN, f"{rel_path} {status}"))
|
||
|
||
# Use '--sync' option
|
||
elif args.sync:
|
||
pages_dirs.remove(root / "pages")
|
||
en_path = root / "pages"
|
||
platforms = [i.name for i in en_path.iterdir() if i.name not in IGNORE_FILES]
|
||
for platform in platforms:
|
||
platform_path = en_path / platform
|
||
commands = [
|
||
f"{platform}/{page.name}"
|
||
for page in platform_path.iterdir()
|
||
if page.name not in IGNORE_FILES
|
||
]
|
||
for command in commands:
|
||
see_also = get_see_also(root / "pages" / command)
|
||
if see_also != "":
|
||
target_paths += sync(
|
||
root, pages_dirs, command, see_also, args.dry_run, args.language
|
||
)
|
||
|
||
# Use '--stage' option
|
||
if args.stage and not args.dry_run and len(target_paths) > 0:
|
||
stage(target_paths)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
main()
|