From eb96cb7b6b0bced88595df7bbed24b649915357f Mon Sep 17 00:00:00 2001 From: Rafael Fontenelle Date: Sun, 19 Jan 2020 19:37:32 -0300 Subject: [PATCH 1/2] Add Makefile and GitHub Actions The Makefile was based on French language team's Makefile, but adapted to Brazilian language team workflow. The GitHub Actions workflow will run this Makefile. Any error will be logged and made available to make it easier to fix. --- .github/workflows/pythonpackage.yml | 81 ++++++++++++ .gitignore | 3 + Makefile | 184 ++++++++++++++++++++++++++++ requirements.txt | 2 + 4 files changed, 270 insertions(+) create mode 100644 .github/workflows/pythonpackage.yml create mode 100644 .gitignore create mode 100644 Makefile create mode 100644 requirements.txt diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml new file mode 100644 index 000000000..c48ff8848 --- /dev/null +++ b/.github/workflows/pythonpackage.yml @@ -0,0 +1,81 @@ +name: Build and update Documentation + +# Daily at 0 am +#on: +# schedule: +# - cron: '0 0 * * *' + +jobs: + build: + + runs-on: ubuntu-latest + strategy: + max-parallel: 4 + matrix: + python-version: [3.7] + + steps: + - uses: actions/checkout@v2 + with: + ref: 3.8 + - run: | + git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/* + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v1 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies via package manager + run: | + sudo apt update + sudo apt install -y gettext + + - name: Prepare virtual environment + run: | + make venv + venv/bin/pip --version + venv/bin/tx --version + venv/bin/sphinx-intl --help + + - name: If failed, make the log file an artifact + if: failure() + uses: actions/upload-artifact@v1 + with: + name: pip-install-log + path: venv/pip-install.log + + - name: Recreate an up-to-date project .tx/config + run: | + make tx-config + + - name: Update translations from Transifex + run: | + if [[ -n "$TRANSIFEX_APIKEY" ]]; then + echo -e "[https://www.transifex.com]\n" \ + "api_hostname = https://api.transifex.com\n" \ + "hostname = https://www.transifex.com\n" \ + "password = $TRANSIFEX_APIKEY\n" \ + "username = api" \ + > ~/.transifexrc + fi + make pull + git status --short + env: + TRANSIFEX_APIKEY: ${{ secrets.TRANSIFEX_APIKEY }} + + - name: Build documentation + run: | + make build CPYTHON_PATH=/tmp/cpython/ SPHINXERRORHANDLING='' + + - name: Push translations + run: | + git config user.email "github-actions[bot]@users.noreply.github.com" + git config user.name "github-actions[bot]" + make push + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Build documentation treating warnings as errors + run: | + make build CPYTHON_PATH=/tmp/cpython/ diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..57427e91d --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +*.mo +.tx/**/*.po +venv/ diff --git a/Makefile b/Makefile new file mode 100644 index 000000000..42872c179 --- /dev/null +++ b/Makefile @@ -0,0 +1,184 @@ +# +# Makefile for Brazilian Portuguese Python Documentation +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +# +# based on: https://github.com/python/python-docs-fr/blob/3.8/Makefile +# + +# Configuration + +CPYTHON_PATH := ../cpython +BRANCH := 3.8 +LANGUAGE_TEAM := python-docs-pt-br +LANGUAGE := pt_BR + +# Internal variables + +UPSTREAM := https://github.com/python/cpython +VENV := $(shell realpath ./venv) +PYTHON := $(shell which python3) +WORKDIRS := $(VENV)/workdirs +CPYTHON_WORKDIR := $(WORKDIRS)/cpython +LOCALE_DIR := $(WORKDIRS)/locale +JOBS := auto +SPHINXERRORHANDLING := "-W" +TRANSIFEX_PROJECT := python-newest + + +.PHONY: help +help: + @echo "Please use 'make ' where is one of:" + @echo " build Build an local version in html, with warnings as errors" + @echo " push Update translations and Transifex config in the repository" + @echo " pull Download translations from Transifex; calls 'venv'" + @echo " tx-config Recreate an up-to-date project .tx/config; calls 'pot'" + @echo " pot Create/Update POT files from source files" + @echo " serve Serve a built documentation on http://localhost:8000" + @echo "" + + +# build: build the documentation using the translation files currently available +# at the moment. For most up-to-date docs, run "tx-config" and "pull" +# before this. If passing SPHINXERRORHANDLING='', warnings will not be +# treated as errors, which is good to skip simple Sphinx syntax mistakes. +.PHONY: build +build: setup + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc/ \ + VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \ + PYTHON=$(PYTHON) \ + SPHINXERRORHANDLING=$(SPHINXERRORHANDLING) \ + SPHINXOPTS='-q --keep-going -j$(JOBS) \ + -D locale_dirs=$(LOCALE_DIR) \ + -D language=$(LANGUAGE) \ + -D gettext_compact=0 \ + -D latex_engine=xelatex \ + -D latex_elements.inputenc= \ + -D latex_elements.fontenc=' \ + html; + + @echo "Success! Open file://$(CPYTHON_WORKDIR)/Doc/build/html/index.html, " \ + "or run 'make serve' to see them in http://localhost:8000"; + + +# push: push new translation files and Transifex config files to repository, +# if any. Do nothing if there is no file changes. If GITHUB_TOKEN is set, +# then assumes we are in GitHub Actions, requiring different push args +.PHONY: push +push: + if ! git status -s | egrep '\.po|\.tx/config'; then \ + echo "Nothing to commit"; \ + exit 0; \ + else \ + git add *.po **/*.po .tx/config; \ + git commit -m 'Update translations'; \ + if [ $(GITHUB_TOKEN) != "" ]; then \ + header="$(echo -n token:"$(GITHUB_TOKEN)" | base64)"; \ + git -c http.extraheader="AUTHORIZATION: basic $(header)" push; \ + else \ + git push; \ + fi; \ + fi + + +# pull: Download translations files from Transifex. For downloading new +# translation files, first run "tx-config" target to update the +# translation file mapping. +.PHONY: pull +pull: venv + $(VENV)/bin/tx pull --force --language=$(LANGUAGE) --parallel + + +# tx-config: After running "pot", create a new Transifex config file by +# reading pot files generated, then tweak this config file to +# LANGUAGE. +.PHONY: tx-config +tx-config: pot + cd $(CPYTHON_WORKDIR)/Doc/locales; \ + rm -rf .tx; \ + $(VENV)/bin/sphinx-intl create-txconfig; \ + $(VENV)/bin/sphinx-intl update-txconfig-resources \ + --transifex-project-name=$(TRANSIFEX_PROJECT) \ + --locale-dir . \ + --pot-dir pot; + + cd $(OLDPWD) + mv $(CPYTHON_WORKDIR)/Doc/locales/.tx/config .tx/config + + sed -i .tx/config \ + -e '/^source_file/d' \ + -e 's|/LC_MESSAGES/||' \ + -e "s|^file_filter|trans.$(LANGUAGE)|" + + +# pot: After running "setup" target, run a cpython Makefile's target +# to generate .pot files under $(CPYTHON_WORKDIR)/Doc/locales/pot +.PHONY: pot +pot: setup + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc/ \ + VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \ + PYTHON=$(PYTHON) \ + ALLSPHINXOPTS='-E -b gettext \ + -D gettext_compact=0 \ + -d build/.doctrees . \ + locales/pot' \ + build + + +# setup: After running "venv" target, prepare that virtual environment with +# a local clone of cpython repository and the translation files. +# If the directories exists, only update the cpython repository and +# the translation files copy which could have new/updated files. +.PHONY: setup +setup: venv + # Setup the main clone + if ! [ -d $(CPYTHON_PATH) ]; then \ + git clone --depth 1 --branch $(BRANCH) $(UPSTREAM) $(CPYTHON_PATH); \ + else \ + git -C $(CPYTHON_PATH) pull --rebase; \ + fi + + # Setup the current work directory + if ! [ -d $(CPYTHON_WORKDIR) ]; then \ + rm -fr $(WORKDIRS); \ + mkdir -p $(WORKDIRS); \ + git clone $(CPYTHON_PATH) $(CPYTHON_WORKDIR); \ + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc \ + VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \ + PYTHON=$(PYTHON) venv; \ + fi + + # Setup translation files + if ! [ -d $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ ]; then \ + mkdir -p $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/; \ + fi; \ + cp --parents *.po **/*.po $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ \ + + +# venv: create a virtual environment which will be used by almost every +# other target of this script +.PHONY: venv +venv: + if [ ! -d $(VENV) ]; then \ + $(PYTHON) -m venv --prompt $(LANGUAGE_TEAM) $(VENV); \ + fi + + $(VENV)/bin/python -m pip install -q -r requirements.txt 2> $(VENV)/pip-install.log + + if grep -q 'pip install --upgrade pip' $(VENV)/pip-install.log; then \ + $(VENV)/bin/pip install -q --upgrade pip; \ + fi + + +# serve: serve the documentation in a simple local web server, using cpython +# Makefile's "serve" target. Run "build" before using this target. +.PHONY: serve +serve: + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc serve + + +# clean: remove all .mo files and the venv directory that may exist and +# could have been created by the actions in other targets of this script +.PHONY: clean +clean: + rm -fr $(VENV) + find -name '*.mo' -delete diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 000000000..863cfbf49 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +transifex-client +sphinx-intl From e97050ed124e8997902dcc7833d086d3160f8385 Mon Sep 17 00:00:00 2001 From: Marco Rougeth Date: Sat, 25 Jan 2020 16:34:24 +0000 Subject: [PATCH 2/2] Enable cron --- .github/workflows/pythonpackage.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml index c48ff8848..43f69075e 100644 --- a/.github/workflows/pythonpackage.yml +++ b/.github/workflows/pythonpackage.yml @@ -1,9 +1,9 @@ name: Build and update Documentation # Daily at 0 am -#on: -# schedule: -# - cron: '0 0 * * *' +on: + schedule: + - cron: '0 0 * * *' jobs: build: