diff --git a/scripts/set-alias-page.py b/scripts/set-alias-page.py new file mode 100644 index 000000000..2fa21991e --- /dev/null +++ b/scripts/set-alias-page.py @@ -0,0 +1,253 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: MIT + +""" +A Python script to generate or update alias pages. +Call the script with --help to get more information. + +For example, add 'vi' as an alias page of 'vim': +python3 script/set-alias-page.py -p common/vi vim + +Read English alias pages and synchronize them into all translations: +python3 script/set-alias-page.py -S +""" + +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-more-info-link.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: + lines = f.readlines() + for line in lines: + if re.search(r"^`tldr ", line): + return re.search("`tldr (.+)`", line).group(1) + return "" + + +def set_alias_page(file, command): + """ + Write an alias page to disk. + + Parameters: + file (string): Path to an alias page + command (string): The command that the alias stands for. + + 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 "" + elif orig_command == "": + status = "\x1b[36mpage added" + else: + status = "\x1b[34mpage updated" + + alias_name = os.path.basename(file[:-3]) + 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): + """ + 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". + + Returns: + str: 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) + 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("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) + + if args.stage: + subprocess.call(["git", "add", *rel_paths], cwd=root) + + +if __name__ == "__main__": + main()