forked from tldr-pages/tldr
-
Notifications
You must be signed in to change notification settings - Fork 0
/
set-page-title.py
executable file
·210 lines (168 loc) · 6.79 KB
/
set-page-title.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""
A Python script to add or update the page title 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-page-title.py [-p PAGE] [-S] [-l LANGUAGE] [-s] [-n] [TITLE]
Options:
-p, --page PAGE
Specify the page in the format "platform/command". This option allows setting the title for a specific page.
-S, --sync
Synchronize each translation's title (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:
TITLE The title to be set as the title.
Examples:
1. Set the title for a specific page:
python3 scripts/set-page-title.py -p common/tar tar
python3 scripts/set-page-title.py --page common/tar tar
2. Synchronize titles across translations:
python3 scripts/set-page-title.py -S
python3 scripts/set-page-title.py --sync
3. Read English pages and synchronize the title for Brazilian Portuguese pages only:
python3 scripts/set-page-title.py -S -l pt_BR
python3 scripts/set-page-title.py --sync --language pt_BR
4. Synchronize titles across translations and stage modified pages for commit:
python3 scripts/set-page-title.py -Ss
python3 scripts/set-page-title.py --sync --stage
5. Show what changes would be made across translations:
python3 scripts/set-page-title.py -Sn
python3 scripts/set-page-title.py --sync --dry-run
"""
from pathlib import Path
from _common import (
IGNORE_FILES,
Colors,
get_tldr_root,
get_pages_dir,
get_target_paths,
get_locale,
get_status,
stage,
create_colored_line,
create_argument_parser,
)
def set_page_title(
path: Path, title: str, dry_run: bool = False, language_to_update: str = ""
) -> str:
"""
Write a title in a page to disk.
Parameters:
path (string): Path to a page
title (string): The title 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[36mtitle added"
"\x1b[34mtitle updated"
"\x1b[36mtitle would be added"
"\x1b[34mtitle would updated"
"""
locale = get_locale(path)
if language_to_update != "" and locale != language_to_update:
# return empty status to indicate that no changes were made
return ""
new_line = f"# {title}\n"
# Read the content of the Markdown file
with path.open(encoding="utf-8") as f:
lines = f.readlines()
if lines[0] == new_line:
# return empty status to indicate that no changes were made
return ""
status = get_status("updated", dry_run, "title")
if not dry_run: # Only write to the path during a non-dry-run
lines[0] = new_line
with path.open("w", encoding="utf-8") as f:
f.writelines(lines)
return status
def get_page_title(path: Path) -> str:
"""
Determine whether the given path has a title.
Parameters:
path (Path): Path to a page
Returns:
str: "" If the path doesn't exit or does not have a title,
otherwise return the page title.
"""
if not path.exists():
return ""
with path.open(encoding="utf-8") as f:
first_line = f.readline().strip()
return first_line.split("#", 1)[-1].strip()
def sync(
root: Path,
pages_dirs: list[Path],
command: str,
title: str,
dry_run: bool = False,
language_to_update: str = "",
) -> list[str]:
"""
Synchronize a page title 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".
title (str): A title like "tar".
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_page_title(path, title, 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 title for all translations of a page")
parser.add_argument("title", type=str, nargs="?", default="")
args = parser.parse_args()
root = get_tldr_root()
pages_dirs = get_pages_dir(root)
target_paths = []
# Use '--page' option
if args.page != "":
target_paths += get_target_paths(args.page, pages_dirs)
for path in target_paths:
rel_path = "/".join(path.parts[-3:])
status = set_page_title(path, args.title)
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:
title = get_page_title(root / "pages" / command)
if title != "":
target_paths += sync(
root, pages_dirs, command, title, 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()