Add Makefile and GitHub Actions

.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/

.gitignore

@@ -0,0 +1,3 @@
+*.mo
+.tx/**/*.po
+venv/

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 <target>' where <target> 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|<lang>/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

requirements.txt

@@ -0,0 +1,2 @@
+transifex-client
+sphinx-intl