#
# Makefile for Brazilian Portuguese Python Documentation
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# based on: https://github.com/python/python-docs-fr/blob/3.8/Makefile
#
#################
# Configuration
# Main translation branch; please make sure it matches 'python-newest'
# project's version in 'python-docs' organization in Transifex
BRANCH := $(shell git branch --show-current)
# Branches representing docs for older Python versions, which current
# translations should be merged into. Here some details:
# - STABLEBRANCH and OLDSTABLEBRANCHES differ in that STABLEBRANCH
# still gets its translated strings overwritten.
# - Not-yet-translated strings will still be merged on both variables
# - Leave STABLEBRANCH empty if Python stable branch is same as BRANCH.
# - Never use same version as in BRANCH
# - Check Python Docs versions still being built and published in:
# https://github.com/python/docsbuild-scripts/blob/master/build_docs.py
STABLEBRANCH := 3.9
OLDSTABLEBRANCHES := 3.8 3.7 3.6 2.7
# Name of language team; should be python-docs-LANG, where LANG is the
# IETF language tag for your language; see Language Tag section in PEP 545
LANGUAGE_TEAM := python-docs-pt-br
# Language code in ISO 639; see Language Tag section in PEP 545, and
# Sphinx configuration's supported languages
LANGUAGE := pt_BR
# Paths and URLs
UPSTREAM := https://github.com/python/cpython
PYTHON := $(shell which python3)
CPYTHON_PATH := $(shell realpath ../cpython)
POSPELL_TMP_DIR := .pospell
VENV := $(shell realpath ./venv)
WORKDIRS := $(VENV)/workdirs
CPYTHON_WORKDIR := $(WORKDIRS)/cpython
LOCALE_DIR := $(WORKDIRS)/locale
# Settings for 'build' target
JOBS := auto
SPHINXERRORHANDLING := "-W"
#
#################
.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 " spell Check spelling, storing output in $(POSPELL_TMP_DIR)"
@echo " merge Merge $(BRANCH) branch's .po files into the following"
@echo " older branches: $(STABLEBRANCH) $(OLDSTABLEBRANCHES)"
@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
@echo "Building Python $(BRANCH) Documentation ..."
@$(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 changed translation files and Transifex config file to repository.
# 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 from Transifex'; \
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, and apply line wrapping.
# 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
@$(VENV)/bin/powrap --quiet *.po **/*.po
# tx-config: After running "pot", create a new Transifex config file by
# reading pot files generated, then tweak it to LANGUAGE.
.PHONY: tx-config
tx-config: TRANSIFEX_PROJECT := python-newest
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;
@mkdir -p .tx
@sed $(CPYTHON_WORKDIR)/Doc/locales/.tx/config \
-e '/^source_file/d' \
-e 's|/LC_MESSAGES/||' \
-e "s|^file_filter|trans.$(LANGUAGE)|" \
> .tx/config
# 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
@if [ -z $(BRANCH) ]; then \
echo "BRANCH is empty, should have git-branch. Unable to continue."; \
exit 1; \
fi
@if ! [ -d $(CPYTHON_PATH) ]; then \
echo "CPython repo not found; cloning ..."; \
git clone --depth 1 --no-single-branch $(UPSTREAM) $(CPYTHON_PATH); \
git -C $(CPYTHON_PATH) checkout $(BRANCH); \
else \
echo "CPython repo found; updating ..."; \
git -C $(CPYTHON_PATH) checkout $(BRANCH); \
git -C $(CPYTHON_PATH) pull --rebase; \
fi
@if ! [ -d $(CPYTHON_WORKDIR) ]; then \
echo "Setting up CPython repo in workdir ..."; \
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; \
else \
echo "CPython repo already ready in workdir"; \
fi
@echo "Setting up translation files in workdir ..."
@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 \
echo "Setting up $(LANGUAGE_TEAM)'s virtual environment ..."; \
$(PYTHON) -m venv --prompt $(LANGUAGE_TEAM) $(VENV); \
$(VENV)/bin/python -m pip install --upgrade pip; \
fi
@$(VENV)/bin/pip install --upgrade --requirement requirements.txt
# 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
# spell: run spell checking tool in all po files listed in SRCS variable,
# storing the output in text files DESTS for proofreading. The
# DESTS target run the spellchecking, while the typos.txt target
# gather all reported issues in one file, sorted without redundancy.
.PHONY: spell
SRCS := $(wildcard *.po **/*.po)
DESTS = $(addprefix $(POSPELL_TMP_DIR)/out/,$(patsubst %.po,%.txt,$(SRCS)))
spell: venv $(DESTS) $(POSPELL_TMP_DIR)/typos.txt
$(POSPELL_TMP_DIR)/out/%.txt: %.po dict
@echo "Checking $< ..."
@mkdir -p $(@D)
@$(VENV)/bin/pospell -l $(LANGUAGE) -p dict $< > $@ || true
$(POSPELL_TMP_DIR)/typos.txt:
@echo "Gathering all typos in $(POSPELL_TMP_DIR)/typos.txt ..."
@cut -d: -f3- $(DESTS) | sort -u > $@
# merge: merge translations from BRANCH (Python version currently aim of
# translation) into each branch listed by STABLEBRANCH and
# OLDSTABLEBRANCHES (branches of older Python versions) so that older
# versions of the Python Docs make at least some use the latest
# translations, if possible. OLDSTABLEBRANCHES has '--no-overwrite'
# flag so it does not overwrite translated strings, preserving history.
# After merging, git-push merged files (if any) to the target branch.
.PHONY: merge
merge: venv $(STABLEBRANCH) $(OLDSTABLEBRANCHES)
$(OLDSTABLEBRANCHES): OVERWRITEFLAG = --no-overwrite
$(STABLEBRANCH) $(OLDSTABLEBRANCHES):
@if [ $@ == $(BRANCH) ]; then \
echo "Ignoring attempt to pomerge '$(BRANCH)' into itself"; \
else \
echo "Merging translations from $(BRANCH) branch into $@ ..."; \
$(VENV)/bin/pomerge --from-files *.po **/*.po; \
git checkout $@; \
$(VENV)/bin/pomerge $(OVERWRITEFLAG) --to-files *.po **/*.po; \
$(VENV)/bin/powrap --modified *.po **/*.po; \
if git status -s | egrep '\.po'; then \
git add *.po **/*.po; \
git commit -m "pomerge from $(BRANCH) branch into $@"; \
git push; \
fi; \
git checkout $(BRANCH); \
fi
# 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 -rf $(VENV)
rm -rf $(POSPELL_TMP_DIR)
find -name '*.mo' -delete