Add sample workflows

sample-workflows/po-lint.yml

@@ -0,0 +1,28 @@
+name: Linting Workflow
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  push:
+    branches:
+      - '*'
+  workflow_dispatch:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version: [ 3.13 ]
+    continue-on-error: true
+    steps:
+      - uses: actions/setup-python@master
+        with:
+          python-version: 3
+      - run: pip install sphinx-lint
+      - uses: actions/checkout@master
+        with:
+          ref: ${{ matrix.version }}
+      - uses: rffontenelle/[email protected]
+      - run: sphinx-lint

sample-workflows/test-build.yml

@@ -0,0 +1,60 @@
+name: Test Build Workflow
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  push:
+    branches:
+      - '*'
+  workflow_dispatch:
+
+jobs:
+  build-translation:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version: [ 3.13 ]
+        format: [ html, latex ]
+    steps:
+      - uses: actions/setup-python@master
+        with:
+          python-version: 3.12  # pinned for Sphinx 3.4.3 to build 3.10
+      - uses: actions/checkout@master
+        with:
+          repository: python/cpython
+          ref: ${{ matrix.version }}
+      - run: make venv
+        working-directory: ./Doc
+      - uses: actions/checkout@master
+        with:
+          ref: ${{ matrix.version }}
+          path: Doc/locales/XX/LC_MESSAGES
+      - run: git pull
+        working-directory: ./Doc/locales/XX/LC_MESSAGES
+      - uses: sphinx-doc/[email protected]
+      - run: make -e SPHINXOPTS="--color -D language='XX' -W --keep-going" ${{ matrix.format }}
+        working-directory: ./Doc
+      - uses: actions/upload-artifact@master
+        if: success() || failure()
+        with:
+          name: build-${{ matrix.version }}-${{ matrix.format }}
+          path: Doc/build/${{ matrix.format }}
+
+    output-pdf:
+      runs-on: ubuntu-latest
+      strategy:
+        matrix:
+          version: [ 3.13 ]
+      needs: [ 'build-translation' ]
+      steps:
+        - uses: actions/download-artifact@master
+          with:
+            name: build-${{ matrix.version }}-latex
+        - run: sudo apt-get update
+        - run: sudo apt-get install -y latexmk texlive-xetex fonts-freefont-otf xindy
+        - run: make
+        - uses: actions/upload-artifact@master
+          with:
+            name: build-${{ matrix.version }}-pdf
+            path: .

sample-workflows/transifex-pull.yml

@@ -0,0 +1,61 @@
+name: Pull Translations from Transifex
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  push:
+    branches:
+      - '*'
+  workflow_dispatch:
+
+jobs:
+  update-translation:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        version: [ 3.13 ]
+    steps:
+      - uses: styfle/cancel-workflow-action@main
+        with:
+          access_token: ${{ secrets.GITHUB_TOKEN }}
+      - uses: actions/setup-python@master
+        with:
+          python-version: 3
+      - name: Install Dependencies
+        run: |
+          sudo apt-get install -y gettext
+          pip install requests cogapp polib transifex-python sphinx-intl blurb six
+          curl -o- https://raw.githubusercontent.com/transifex/cli/master/install.sh | bash
+        working-directory: /usr/local/bin
+      - uses: actions/checkout@master
+        with:
+          ref: ${{ matrix.version }}
+          fetch-depth: 0
+      - run: curl https://raw.githubusercontent.com/python-docs-translations/transifex-automation/master/sample-workflows/transifex-util.py
+      - run: ./manage_translation.py recreate_tx_config --language XX --project-slug python-newest --version 3.13
+        env:
+          TX_TOKEN: ${{ secrets.TX_TOKEN }}
+      - run: ./manage_translation.py fetch --language XX --project-slug python-newest --version 3.13
+        env:
+          TX_TOKEN: ${{ secrets.TX_TOKEN }}
+      - run: ./manage_translation.py delete_obsolete_files --language XX --project-slug python-newest --version 3.13
+      - name: Set up Git
+        run: |
+          git config --local user.email [email protected]
+          git config --local user.name "GitHub Action's update-translation job"
+      - name: Filter files
+        run: |
+          ! git diff -I'^"POT-Creation-Date: ' \
+                     -I'^"Language-Team: ' \
+                     -I'^# ' -I'^"Last-Translator: ' \ 
+                     --exit-code \
+            && echo "SIGNIFICANT_CHANGES=1" >> $GITHUB_ENV || exit 0
+      - run: git add .
+      - run: git commit -m 'Update translation from Transifex'
+        if: env.SIGNIFICANT_CHANGES
+      - uses: ad-m/github-push-action@master
+        if: env.SIGNIFICANT_CHANGES
+        with:
+          branch: ${{ matrix.version }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}

sample-workflows/transifex-util.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+#
+# This python file contains utility scripts to manage Python docs translation
+# on Transifex.
+#
+# Inspired by django-docs-translations script by claudep.
+import configparser
+from argparse import ArgumentParser
+import os
+from contextlib import chdir
+from pathlib import Path
+from subprocess import call
+import sys
+from tempfile import TemporaryDirectory
+
+from polib import pofile
+from transifex.api import transifex_api
+
+
+def fetch():
+    """
+    Fetch translations from Transifex, remove source lines.
+    """
+    if (code := call("tx --version", shell=True)) != 0:
+        sys.stderr.write("The Transifex client app is required.\n")
+        exit(code)
+    lang = LANGUAGE
+    _call(f'tx pull -l {lang} --minimum-perc=1 --force --skip')
+    for file in Path().rglob('*.po'):
+        _call(f'msgcat --no-location -o {file} {file}')
+
+def _call(command: str):
+    if (return_code := call(command, shell=True)) != 0:
+        exit(return_code)
+
+def recreate_tx_config():
+    """
+    Regenerate Transifex client config for all resources.
+    """
+    with TemporaryDirectory() as directory:
+        with chdir(directory):
+            _clone_cpython_repo(VERSION)
+            _build_gettext()
+            with chdir(Path(directory) / 'cpython/Doc/build'):
+                _create_txconfig()
+                _update_txconfig_resources()
+                with open('.tx/config', 'r') as file:
+                    contents = file.read()
+        contents = contents.replace('./<lang>/LC_MESSAGES/', '')
+        with open('.tx/config', 'w') as file:
+            file.write(contents)
+
+def delete_obsolete_files():
+    files_to_delete = list(_get_files_to_delete())
+    if not files_to_delete:
+        return
+    else:
+        for file in files_to_delete:
+            print(f"Removing {file}")
+            os.remove(file)
+            _call(f'git rm --quiet "{file}"')
+
+def _get_files_to_delete():
+    with open('.tx/config') as config_file:
+        config = config_file.read()
+    for file in Path().rglob('*.po'):
+        if os.fsdecode(file) not in config:
+            yield os.fsdecode(file)
+
+def _clone_cpython_repo(version: str):
+    _call(f'git clone -b {version} --single-branch https://github.com/python/cpython.git --depth 1')
+
+def _build_gettext():
+    _call("make -C cpython/Doc/ gettext")
+
+def _create_txconfig():
+    _call('sphinx-intl create-txconfig')
+
+def _update_txconfig_resources():
+    _call(
+        f'sphinx-intl update-txconfig-resources --transifex-organization-name python-doc '
+        f'--transifex-project-name={PROJECT_SLUG} --locale-dir . --pot-dir gettext'
+    )
+
+def _get_tx_token() -> str:
+    if os.path.exists('.tx/api-key'):
+        with open('.tx/api-key') as f:
+            return f.read()
+
+    config = configparser.ConfigParser()
+    config.read(os.path.expanduser("~/.transifexrc"))
+    try:
+        return config["https://www.transifex.com"]["token"]
+    except KeyError:
+        pass
+
+    return os.getenv('TX_TOKEN', '')
+
+if __name__ == "__main__":
+    RUNNABLE_SCRIPTS = ('fetch', 'recreate_tx_config', 'delete_obsolete_files')
+
+    parser = ArgumentParser()
+    parser.add_argument('cmd', choices=RUNNABLE_SCRIPTS)
+    parser.add_argument('--language', required=True)
+    parser.add_argument('--project-slug', required=True)
+    parser.add_argument('--version', required=True)
+
+    options = parser.parse_args()
+
+    LANGUAGE = options.language
+    PROJECT_SLUG = options.project_slug
+    VERSION = options.version
+
+    globals()[options.cmd]()