#!/usr/bin/env python3 # SPDX-License-Identifier: MIT """ A Python script to generate or update alias pages. Disclaimer: This script generates a lot of false positives so it isn't suggested to use the sync option. If used, only stage changes and commit verified changes for your language. Note: If there is a symlink error when using the stage flag remove the `pages.en` directory temporarily and try executing it again. Usage: python3 scripts/set-alias-page.py [-p PAGE] [-s] [-S] [-n] [COMMAND] Options: -p, --page PAGE Specify the alias page in the format "platform/alias_command.md". -s, --stage Stage modified pages (requires 'git' on $PATH and TLDR_ROOT to be a Git repository). -S, --sync Synchronize each translation's alias page (if exists) with that of the English page. -n, --dry-run Show what changes would be made without actually modifying the page. Examples: 1. Add 'vi' as an alias page of 'vim': python3 scripts/set-alias-page.py -p common/vi vim 2. Read English alias pages and synchronize them into all translations: python3 scripts/set-alias-page.py -S 3. Read English alias pages and show what changes would be made: python3 scripts/set-alias-page.py -Sn python3 scripts/set-alias-page.py --sync --dry-run """ import argparse import os import re import subprocess IGNORE_FILES = (".DS_Store", "tldr.md", "aria2.md") def get_tldr_root(): """ Get the path of local tldr repository for environment variable TLDR_ROOT. """ # If this script is running from tldr/scripts, the parent's parent is the root f = os.path.normpath(__file__) if f.endswith("tldr/scripts/set-alias-page.py"): return os.path.dirname(os.path.dirname(f)) if "TLDR_ROOT" in os.environ: return os.environ["TLDR_ROOT"] else: raise SystemExit( "\x1b[31mPlease set TLDR_ROOT to the location of a clone of https://github.com/tldr-pages/tldr.\x1b[0m" ) def get_templates(root): """ Get all alias page translation templates from TLDR_ROOT/contributing-guides/translation-templates/alias-pages.md. Parameters: root (string): The path of local tldr repository, i.e., TLDR_ROOT. Returns: dict of (str, str): Language labels map to alias page templates. """ template_file = os.path.join( root, "contributing-guides/translation-templates/alias-pages.md" ) with open(template_file) as f: lines = f.readlines() # Parse alias-pages.md templates = {} i = 0 while i < len(lines): if lines[i].startswith("###"): lang = lines[i][4:].strip("\n").strip(" ") while True: i = i + 1 if lines[i].startswith("Not translated yet."): is_translated = False break elif lines[i].startswith("```markdown"): i = i + 1 is_translated = True break if is_translated: text = "" while not lines[i].startswith("```"): text += lines[i] i = i + 1 templates[lang] = text i = i + 1 return templates def get_alias_page(file): """ Determine whether the given file is an alias page. Parameters: file (string): Path to a page Returns: str: "" If the file doesn't exit or is not an alias page, otherwise return what command the alias stands for. """ if not os.path.isfile(file): return "" with open(file) as f: for line in f: if match := re.search(r"^`tldr (.+)`", line): return match[1] return "" def set_alias_page(file, command, dry_run=False): """ Write an alias page to disk. Parameters: file (string): Path to an alias page command (string): The command that the alias stands for. dry_run (bool): Whether to perform a dry-run. Returns: str: Execution status "" if the alias page standing for the same command already exists. "\x1b[36mpage added" if it's a new alias page. "\x1b[34mpage updated" if the command updates. """ # compute locale pages_dir = os.path.basename(os.path.dirname(os.path.dirname(file))) if "." in pages_dir: _, locale = pages_dir.split(".") else: locale = "en" if locale not in templates: return "" # Test if the alias page already exists orig_command = get_alias_page(file) if orig_command == command: return "" if orig_command == "": status_prefix = "\x1b[36m" action = "added" else: status_prefix = "\x1b[34m" action = "updated" if dry_run: status = f"page will be {action}" else: status = f"page {action}" status = f"{status_prefix}{status}\x1b[0m" if not dry_run: # Only write to the file during a non-dry-run alias_name, _ = os.path.splitext(os.path.basename(file)) text = ( templates[locale] .replace("example", alias_name, 1) .replace("example", command) ) os.makedirs(os.path.dirname(file), exist_ok=True) with open(file, "w") as f: f.write(text) return status def sync(root, pages_dirs, alias_name, orig_command, dry_run=False): """ Synchronize an alias page into all translations. Parameters: root (str): TLDR_ROOT pages_dirs (list of str): Strings of page entry and platform, e.g. "page.fr/common". alias_name (str): An alias command with .md extension like "vi.md". orig_command (string): An Original command like "vim". dry_run (bool): Whether to perform a dry-run. Returns: list: A list of paths to be staged into git, using by --stage option. """ rel_paths = [] for page_dir in pages_dirs: path = os.path.join(root, page_dir, alias_name) status = set_alias_page(path, orig_command, dry_run) if status != "": rel_path = path.replace(f"{root}/", "") rel_paths.append(rel_path) print(f"\x1b[32m{rel_path} {status}\x1b[0m") return rel_paths def main(): parser = argparse.ArgumentParser( description="Sets the alias page for all translations of a page" ) parser.add_argument( "-p", "--page", type=str, required=False, default="", help='page name in the format "platform/alias_command.md"', ) parser.add_argument( "-s", "--stage", action="store_true", default=False, help="stage modified pages (requires `git` to be on $PATH and TLDR_ROOT to be a Git repository)", ) parser.add_argument( "-S", "--sync", action="store_true", default=False, help="synchronize each translation's alias page (if exists) with that of English page", ) parser.add_argument( "-n", "--dry-run", action="store_true", default=False, help="show what changes would be made without actually modifying the pages", ) parser.add_argument("command", type=str, nargs="?", default="") args = parser.parse_args() root = get_tldr_root() # A dictionary of all alias page translations global templates templates = get_templates(root) pages_dirs = [d for d in os.listdir(root) if d.startswith("pages")] rel_paths = [] # Use '--page' option if args.page != "": if not args.page.lower().endswith(".md"): args.page = f"{args.page}.md" target_paths = [os.path.join(root, p, args.page) for p in pages_dirs] target_paths.sort() for path in target_paths: rel_path = path.replace(f"{root}/", "") rel_paths.append(rel_path) status = set_alias_page(path, args.command) if status != "": print(f"\x1b[32m{rel_path} {status}\x1b[0m") # Use '--sync' option elif args.sync: pages_dirs.remove("pages") en_page = os.path.join(root, "pages") platforms = [i for i in os.listdir(en_page) if i not in IGNORE_FILES] for platform in platforms: platform_path = os.path.join(en_page, platform) commands = [ f"{platform}/{p}" for p in os.listdir(platform_path) if p not in IGNORE_FILES ] for command in commands: orig_command = get_alias_page(os.path.join(root, "pages", command)) if orig_command != "": rel_paths += sync( root, pages_dirs, command, orig_command, args.dry_run ) # Use '--stage' option if args.stage and not args.dry_run: subprocess.call(["git", "add", *rel_paths], cwd=root) if __name__ == "__main__": main()