diff --git a/.github/workflows/pythonpackage.yml b/.github/workflows/pythonpackage.yml new file mode 100644 index 000000000..43f69075e --- /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