Merge branch '3.12' into feature/upgrade-makefile

Author: josix

.github/workflows/ci.yml

@@ -13,4 +13,4 @@ jobs:
         run: sudo apt-get install gettext
 
       - name: Validate
-        run: VERSION=${{ github.event.pull_request.base.ref }} MODE=dummy make all
+        run: VERSION=${{ github.event.repository.default_branch }} MODE=dummy make all

.github/workflows/summarize_progress.yml

@@ -0,0 +1,43 @@
+name: summarize_progress
+
+on:
+  schedule:
+    - cron:  '30 23 * * 5'
+
+jobs:
+  ci:
+    if: github.repository == 'python/python-docs-zh-tw'
+    runs-on: ubuntu-latest
+    permissions:
+        # Give the default GITHUB_TOKEN write permission to commit and push the
+        # added or changed files to the repository.
+        contents: write
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+
+      - name: Execute Check Process
+        run: |
+            chmod +x .scripts/summarize_progress.sh 
+            .scripts/summarize_progress.sh
+        shell: bash
+      
+
+      - name: Checkout wiki code
+        uses: actions/checkout@v2
+        with:
+          repository: ${{github.repository}}.wiki
+          path: markdown
+      
+      - name: Copy content
+        run: |
+            cp .scripts/summarize_progress/result.md markdown/各檔案翻譯進度清單.md
+        shell: bash
+
+      - name: Commit wiki code
+        uses: stefanzweifel/git-auto-commit-action@v5
+        with:
+            commit_message: Weekly Update -- Summarize Progress
+            repository: markdown

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+# Install the pre-commit hooks below with
+# 'pre-commit install'
+
+# Auto-update the version of the hooks with
+# 'pre-commit autoupdate'
+
+repos:
+- repo: https://git.afpy.org/AFPy/powrap
+  # there's no release tag in repo, use the latest commit hash id instead
+  rev: a34a9fed116d24562fbe4bb8d456ade85f056c36
+  hooks:
+  - id: powrap

.scripts/poetry.lock

@@ -10,7 +10,7 @@ python = "^3.10"
 polib = "1.1.1"
 googletrans = "3.1.0a0"
 translate-toolkit = "3.8.1"
-
+requests = "2.31.0"
 
 [build-system]
 requires = ["poetry-core"]

.scripts/pyproject.toml

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+WORK_DIR=.scripts
+cd $WORK_DIR
+
+source utils/install_poetry.sh
+
+poetry lock
+poetry install
+poetry run bash -c "
+    python summarize_progress/main.py
+"

.scripts/summarize_progress.sh

@@ -0,0 +1,161 @@
+import re
+import polib
+import glob
+import requests
+
+from pathlib import Path
+
+
+def entry_check(pofile: polib.POFile) -> str:
+    '''
+    Check the po file with how many entries are translated or not.
+    '''
+
+    lines_tranlated = len(pofile.translated_entries())
+    lines_untranlated = len(pofile.untranslated_entries())
+
+    if lines_tranlated == 0:
+        result = "❌"
+    elif lines_untranlated == 0:
+        result = "✅"
+    else:
+        lines_all = lines_tranlated + lines_untranlated
+        progress = lines_tranlated / lines_all
+        progress_percentage = round(progress * 100, 2)
+        result = f"{progress_percentage} %"
+
+    return result
+
+
+def get_open_issues_count() -> int:
+    '''
+    Fetch GitHub API to get the number of OPEN ISSUES.
+    '''
+
+    url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open"
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    r = requests.get(url=url, headers=headers)
+    result = r.json()
+
+    return result["total_count"]
+
+
+def get_github_issues() -> list:
+    '''
+    Fetch GitHub API to collect the infomation of OPEN ISSUES,
+    including issue title and assignee.
+
+    Steps:
+    1. Fetch GitHub API and get open issue list
+    2. Filter the issue if it have no "Translate" in the title
+    3. Filter the issue if it have no correct filepath in the title
+
+    Expected Output:
+    [ ((dirname, filename), assignee_id, issue_url), ... ]
+    '''
+    NUMBER_OF_ISSUES = get_open_issues_count()
+
+    url = f"https://api.github.com/search/issues?q=repo:python/python-docs-zh-tw+type:issue+state:open&per_page={NUMBER_OF_ISSUES}"
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    r = requests.get(url=url, headers=headers)
+    result = r.json()
+
+    result_list = []
+    for issue in result["items"]:
+        assignee = issue["assignee"]["login"] if issue["assignee"] else ""
+
+        title = issue["title"]
+        if "翻譯" not in title and "translate" not in title.lower():
+            continue
+
+        match = re.search(
+            "(?P<dirname>[^\s`][a-zA-z-]+)/(?P<filename>[a-zA-Z0-9._-]+(.po)?)", title)
+        if not match:
+            continue
+
+        dirname, filename = match.group('dirname', 'filename')
+        if not filename.endswith('.po'):
+            filename += '.po'
+
+        result_list.append(((dirname, filename), assignee, issue["html_url"]))
+
+    return result_list
+
+
+def format_line_table_header() -> list:
+    return [f"|Filename|Progress|Issue|Assignee|\r\n",
+            f"|-------:|:-------|:----|:-------|\r\n"]
+
+
+def format_issue_link(url: str) -> str:
+    return f"[{url.split('/')[-1]}]({url})" if len(url) > 0 else ''
+
+
+def format_line_file(filename: str, data: dict) -> str:
+    return f"|`{filename}`|{data['progress']}|{format_issue_link(data['issue'])}|{data['assignee']}|\r\n"
+
+
+def format_line_directory(dirname: str) -> str:
+    return f"## {dirname}\r\n"
+
+
+if __name__ == "__main__":
+    issue_list = get_github_issues()
+
+    '''
+    Search all the po file in the directory,
+    and record the translation progress of each files.
+    '''
+    BASE_DIR = Path("../")
+    summary = {}
+    for filepath in glob.glob(str(BASE_DIR / "**/*.po"), recursive=True):
+        path = Path(filepath)
+        filename = path.name
+        dirname = path.parent.name if path.parent.name != BASE_DIR.name else '/'
+        po = polib.pofile(filepath)
+
+        summary.setdefault(dirname, {})[filename] = {
+            'progress': entry_check(po),
+            'issue': '',
+            'assignee': '',
+        }
+
+    '''
+    Unpack the open issue list, and add assignee after the progress
+    '''
+    for (category, filename), assignee, issue_url in issue_list:
+        try:
+            summary[category][filename]['issue'] = issue_url
+            summary[category][filename]['assignee'] = assignee
+        except KeyError:
+            pass
+
+    '''
+    Adding Space for Formatting Markdown Link
+    '''
+
+    '''
+    Format the lines that will write into the markdown file,
+    also sort the directory name and file name.
+    '''
+    writeliner = []
+    summary_sorted = dict(sorted(summary.items()))
+    for dirname, filedict in summary_sorted.items():
+        writeliner.append(format_line_directory(dirname))
+        writeliner.extend(format_line_table_header())
+
+        filedict_sorted = dict(sorted(filedict.items()))
+        for filename, filedata in filedict_sorted.items():
+            writeliner.append(format_line_file(filename, filedata))
+
+    with open(
+        f"summarize_progress/result.md",
+        "w",
+    ) as file:
+        file.writelines(writeliner)

.scripts/summarize_progress/main.py

@@ -98,14 +98,16 @@ $(VENV)/bin/activate:
 $(VENV)/bin/sphinx-build: $(VENV)/bin/activate
 	. $(VENV)/bin/activate; python3 -m pip install sphinx python-docs-theme
 
+$(VENV)/bin/sphinx-lint: $(VENV)/bin/activate
+	. $(VENV)/bin/activate; python3 -m pip install sphinx-lint
 
 $(VENV)/bin/blurb: $(VENV)/bin/activate
 	. $(VENV)/bin/activate; python3 -m pip install blurb
 
 
 .PHONY: upgrade_venv
 upgrade_venv: $(VENV)/bin/activate ## Upgrade the venv that compiles the doc
-	. $(VENV)/bin/activate; python3 -m pip install --upgrade sphinx python-docs-theme blurb
+	. $(VENV)/bin/activate; python3 -m pip install --upgrade sphinx python-docs-theme blurb sphinx-lint
 
 
 .PHONY: progress
@@ -134,10 +136,7 @@ endif
 	        mkdir -p "$$(dirname "$$PO")";\
 	        if [ -f "$$PO" ];\
 	        then\
-	            case "$$POT" in\
-	            *whatsnew*) msgmerge --lang=$(LANGUAGE) --backup=off --force-po --no-fuzzy-matching -U "$$PO" "$$POT" ;;\
-	            *)          msgmerge --lang=$(LANGUAGE) --backup=off --force-po -U "$$PO" "$$POT" ;;\
-	            esac\
+	            msgmerge --lang=$(LANGUAGE) --backup=off --force-po -U "$$PO" "$$POT";\
 	        else\
 	            msgcat --lang=$(LANGUAGE) -o "$$PO" "$$POT";\
 	        fi\
@@ -160,6 +159,10 @@ fuzzy: ## Find fuzzy strings
 rm_cpython: ## Remove cloned cpython repo
 	rm -rf $(CPYTHON_CLONE)
 
+.PHONY: lint
+lint:  $(VENV)/bin/sphinx-lint  ## Run sphinx-lint
+	$(VENV)/bin/sphinx-lint --enable default-role
+
 # This allows us to accept extra arguments (by doing nothing when we get a job that doesn't match, rather than throwing an error)
 %:
 	@:

Makefile

@@ -89,12 +89,17 @@ the PSF for inclusion in the documentation.
   brew install gettext
 
   brew link gettext --force
+- 安裝 pre-commit 自動在 commit 時檢查 ``.po`` 檔格式。
+.. code-block:: bash
+
+  pip install pre-commit
+  pre-commit install
 
 在進行任何動作以前，你必須在 GitHub 上 fork 此專案（按下右上角的 ``Fork``
 按鈕），這樣會把整個專案複製一份到你的 GitHub 帳號底下，你可以對這個 fork
 進行修改。
 
-第一次貢獻以前（還沒有 clone 過)
+第一次貢獻以前（還沒有 clone 過）
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 請在 terminal 裡依照以下步驟：
@@ -118,7 +123,7 @@ the PSF for inclusion in the documentation.
 .. _GitHub Flow: https://guides.github.com/introduction/flow/
 
 首先，`新增一個 issue <https://github.com/python/python-docs-zh-tw/issues>`_\
-，如：「翻譯 tutorial/introduction.po」，讓大家知道你正在翻譯這個檔案。可以使用 `make todo` 列出尚待翻譯的檔案。
+，如：「翻譯 tutorial/introduction.po」，讓大家知道你正在翻譯這個檔案。可以使用 ``make todo`` 列出尚待翻譯的檔案。
 
 接著在 terminal 裡按照以下步驟：
 
@@ -133,12 +138,18 @@ the PSF for inclusion in the documentation.
 
     poedit glossary.po
 
-3. 存檔以後，執行以下列指令編譯輸出文件，以確保你的修改沒有 rST 的語法錯誤或警告 ::
+3. 存檔以後，執行以下列指令編譯輸出完整文件，以確保你的修改沒有 reST 的語法錯誤或警告 ::
 
     VERSION=3.12 make all
 
+   或者只想快速檢查是否有 reST 語法錯誤 ::
+
+    VERSION=3.12 make lint
+
+   確保輸出中沒有任何關於正在翻譯的檔案的警告訊息。
+
    如果你還沒有執行 `維護、預覽`_ 的 clone CPython 的動作，此指令會自動幫你 clone CPython，\
-   並且會使用 Sphinx 幫你檢查 rST 語法錯誤，我們盡量保持沒有 warning \
+   並且會使用 Sphinx 幫你檢查 reST 語法錯誤，我們盡量保持沒有 warning \
    的狀態，因此如果有出現 warning 的話請修復它。另外也記得檢查是否符合\
    `翻譯守則`_
 
@@ -247,11 +258,11 @@ po 檔皆為首要的翻譯對象。你也可以幫忙校對已經翻譯過的
 - 在本情況使用 ``zip(*[iter(x)]*n)`` 是很常見的情況（Python 慣例）。
 - 在超文件標示語言 (HTML) 中應注意跳脫符號。
 
-rST 語法注意事項
+reST 語法注意事項
 ----------------
 
-- ``:xxx:`...``` 即為 rST 的語法，應該在譯文中保留。
-- rST 諸多語法需要保留前後的空白。在中文裡，該空白可以用 :literal:`\\\  \ `
+- ``:xxx:`...``` 即為 reST 的語法，應該在譯文中保留。
+- reST 諸多語法需要保留前後的空白。在中文裡，該空白可以用 :literal:`\\\  \ `
   來取代，製造一個沒有寬度的分隔符號。
 
   例如：
@@ -307,18 +318,13 @@ rST 語法注意事項
 
   .. code-block:: rst
 
-    以下是個程式範例：
-
-    ::
-
-  注意\ **額外的空行是必須的**。
-
+    以下是個程式範例： ::
 
 術語表 Glossary
 ===============
 
-為了讓翻譯保持統一，我們整理了一份 `術語列表 
-<https://github.com/python/python-docs-zh-tw/wiki/%E8%A1%93%E8%AA%9E%E5%88%97%E8%A1%A8>`_ \
+為了讓翻譯保持統一，我們整理了一份 \
+`術語列表 <https://github.com/python/python-docs-zh-tw/wiki/%E8%A1%93%E8%AA%9E%E5%88%97%E8%A1%A8>`_ \
 如果翻譯過程中你覺得需要術語列表有所缺漏，請至 `Discussion \
 <https://github.com/python/python-docs-zh-tw/discussions>`_ 開啟新的討論補充術語。\
 新增的術語，將會於每次 Sprint 中共同討論是否合併進術語列表。

README.rst

@@ -13,7 +13,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Python 3.12\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2023-02-27 00:17+0000\n"
+"POT-Creation-Date: 2023-11-05 09:50+0000\n"
 "PO-Revision-Date: 2022-08-31 12:34+0800\n"
 "Last-Translator: Steven Hsu <[email protected]>\n"
 "Language-Team: Chinese - TAIWAN (https://github.com/python/python-docs-zh-"
@@ -117,9 +117,10 @@ msgstr "給有意成為 Python 說明文件貢獻者的綜合指南。"
 
 #: ../../bugs.rst:41
 msgid ""
-"`Documentation Translations <https://devguide.python.org/documenting/"
-"#translating>`_"
-msgstr "`說明文件翻譯 <https://devguide.python.org/documenting/#translating>`_"
+"`Documentation Translations <https://devguide.python.org/documentation/"
+"translating/>`_"
+msgstr ""
+"`說明文件翻譯 <https://devguide.python.org/documentation/translating/>`_"
 
 #: ../../bugs.rst:42
 msgid ""