Makefile

#
# Makefile for Brazilian Portuguese Python Documentation
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
#  based on: https://github.com/python/python-docs-fr/blob/3.8/Makefile
#

#################
# Configuration

# Read environment variables from file to keep this clean move version
# changes elsewhere
include .env

# Force the use of Bash
SHELL=/bin/bash

# Time of starting this run
NOW                    := $(shell date +'%Y%m%-d-%H%M%Z')

# Force realpath, not relative one
override CPYTHON_DIR   := $(shell realpath $(CPYTHON_DIR))

override LOGS_DIR      := $(shell realpath $(LOGS_DIR))

override VENV_DIR      := $(shell realpath $(VENV_DIR))
#
#################

.PHONY: build clean help htmlview lint merge pot pull push setup spell tx-config tx-install venv

help:
	@echo "Please use 'make <target>' where <target> is one of:"
	@echo " build        Build an local version in html; deps: 'setup'"
	@echo " push         Commit and push translations; no deps"
	@echo " pull         Download translations from Transifex; deps: 'tx-config'"
	@echo " tx-config    Regenerate Transifex config; deps: 'pot' and 'tx-install'"
	@echo " tx-install   Install Transifex CLI client; deps: no deps"
	@echo " pot          Regenerate POT files from sources; deps: 'setup'"
	@echo " htmlview     View docs in a web browser; deps: build"
	@echo " spell        Check spelling, storing output in $(POSPELL_TMP_DIR)"
	@echo " lint         Do some linting in PO file's Sphinx syntax. deps: 'venv'"
	@echo " merge        Merge $(BRANCH) branch's .po files into older branches"
	@echo "                Defaults overwrite in: $(BUGFIXBRANCH)"
	@echo "                and NOT overwrite in: $(OLDERBRANCHES)"
	@echo " clean        Do some house cleaning"
	@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.
build: setup
	@mkdir -p "$(CPYTHON_DIR)/$(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/"
	@cp --parents *.po **/*.po "$(CPYTHON_DIR)/$(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/"
	@echo "Building Python $(BRANCH) Documentation in $(LANGUAGE) ..."
	@mkdir -p "$(LOGS_DIR)/build"
	@$(MAKE) -C $(CPYTHON_DIR)/Doc/ \
	    PYTHON=$(PYTHON) \
	    SPHINXERRORHANDLING=$(SPHINXERRORHANDLING) \
	    SPHINXOPTS="--keep-going \
	        -D gettext_compact=0 \
	        -D language=$(LANGUAGE) \
	        -D latex_engine=xelatex \
	        -D latex_elements.inputenc= \
	        -D latex_elements.fontenc=" \
	    html \
	    2> >(tee -a $(LOGS_DIR)/build/err-$(NOW).txt >&2)


# push: Commit and push translation files and Transifex config file to repo.
#       First it git-adds tracked file that doesn't exclusively match changes
#       in POT-Creation-Date header field. Then it git-adds untracked PO files
#       that might have been created in the update process, and the Transifex
#       configuration. Finally, only commit and push only if any file was
#       git-added (staged); otherwise, it does nothing.
#       The MSG variable has a default commit message, but one can override it
#       e.g. make push MSG='my message'
push:
	@git diff -I'^"POT-Creation-Date: ' --numstat *.po **/*.po | cut -f3 | xargs -r git add
	@git add $(shell git ls-files -o *.po **/*.po) .tx/config
	@git diff-index --cached --quiet HEAD || \
	{ git commit -m "Update translations from Transifex" && git push; }


# 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.
pull: tx-config
	@"$(TX_CLI_DIR)/tx" pull -l $(LANGUAGE) -t -f --use-git-timestamps
	@"$(VENV_DIR)/bin/powrap" --quiet *.po **/*.po


# tx-config: Generate a new Transifex configuration file by reading
#            the pot files generated by 'pot' target. The file is
#            created in $(LOCALE_DIR)/.tx/config, and then is tweaked
#            to fit the language's needs and then placed in .tx/config
#            at the project's root directory.
tx-config: TRANSIFEX_PROJECT := python-newest
tx-config: pot tx-install
	@cd $(CPYTHON_DIR)/$(LOCALE_DIR); \
	rm -rf .tx; \
	"$(VENV_DIR)/bin/sphinx-intl" create-txconfig; \
	"$(VENV_DIR)/bin/sphinx-intl" update-txconfig-resources \
	    --transifex-organization-name python-doc \
	    --transifex-project-name=$(TRANSIFEX_PROJECT) \
	    --locale-dir . \
	    --pot-dir pot
	@mkdir -p .tx
	@sed $(CPYTHON_DIR)/$(LOCALE_DIR)/.tx/config \
	    -e "s|^file_filter *= .*|&\nx&|;" \
	    -e "s|= pot/|= ../../pot/|" \
	    > .tx/config
	@sed -i .tx/config \
	    -e "s|^xfile_filter *= ./<lang>/LC_MESSAGES/|trans.$(LANGUAGE)            = |;"


# tx-install: Install Transifex CLI client if not installed yet. Installs
#             the TX_CLI_VERSION version into TX_CLI_DIR directory. If
#             TX_CLI_VERSION not provided, uses the latest one.
tx-install: URL := https://raw.githubusercontent.com/transifex/cli/master/install.sh
tx-install:
	@if [ ! -x "$(TX_CLI_DIR)/tx" ]; then \
	    echo "Transifex TX Client not found, installing ..."; \
	    cd "$(TX_CLI_DIR)"; \
	    if [ -n "v$(TX_CLI_VERSION)" ]; then \
	        curl -s -o- $(URL) | bash -s -- v$(TX_CLI_VERSION); \
	    else \
	        curl -s -o- $(URL) | bash; \
	    fi; \
	fi


# pot: After running "setup" target, run sphinx-build's gettext target
#      to generate .pot files under $(CPYTHON_DIR)/Doc/locales/pot.
pot: setup
	@$(MAKE) -C $(CPYTHON_DIR)/Doc/ \
	    VENVDIR=./venv \
	    PYTHON=$(PYTHON) \
	    ALLSPHINXOPTS='-E \
	        -b gettext \
	        -D gettext_compact=0 \
	        -d build/.doctrees \
	        . $(CPYTHON_DIR)/$(LOCALE_DIR)/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.
setup: CPYTHON_URL := https://github.com/python/cpython
setup: venv
	@if [ -z "$(BRANCH)" ]; then \
	    echo "BRANCH is empty, should have git-branch. Unable to continue."; \
	    exit 1; \
	fi
	
	@if ! [ -d "$(CPYTHON_DIR)" ]; then \
	    echo "CPython repo not found; cloning ..."; \
	    git clone --depth 1 --no-single-branch $(CPYTHON_URL) $(CPYTHON_DIR); \
	    git -C "$(CPYTHON_DIR)" checkout $(BRANCH); \
	else \
	    echo "CPython repo found; updating ..."; \
	    git -C "$(CPYTHON_DIR)" checkout $(BRANCH); \
	    git -C "$(CPYTHON_DIR)" pull --rebase; \
	fi
	
	@echo "Creating CPython's documentation virtual environment ..."
	@if [ ! -d "$(CPYTHON_DIR)/Doc/venv" ]; then \
	    $(MAKE) -C "$(CPYTHON_DIR)/Doc" PYTHON=$(PYTHON) venv; \
	fi


# venv: create a virtual environment which will be used by almost every
#       other target of this script. CPython specific packages are installed
#       in there specific venv (see 'setup' target).
venv:
	@if [ ! -d "$(VENV_DIR)" ]; then \
	    echo "Setting up language team's virtual environment ..."; \
	    "$(PYTHON)" -m venv "$(VENV_DIR)"; \
	    "$(VENV_DIR)/bin/python" -m pip install --upgrade pip; \
	    mkdir -p "$(LOGS_DIR)"; \
	    "$(VENV_DIR)/bin/pip" install --requirement requirements.txt \
	        --log "$(LOGS_DIR)/venv-$(NOW).txt"; \
	fi


# htmlview: View the documentation locally, using Makefile's "htmlview" target.
#           Run "build" before using this target.
htmlview: build
	@INDEX="$(CPYTHON_DIR)/Doc/build/html/index.html"; \
	"$(PYTHON)" -c "import os, webbrowser; \
	webbrowser.open('file://' + os.path.realpath('$$INDEX'))"


# 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.
SRCS := $(wildcard *.po **/*.po)
DESTS := $(addprefix $(LOGS_DIR)/pospell-$(NOW)/out/,$(patsubst %.po,%.txt,$(SRCS)))
spell: venv $(DESTS) $(LOGS_DIR)/pospell-$(NOW)/all.txt

$(LOGS_DIR)/pospell-$(NOW)/out/%.txt: %.po dict
	@echo "Checking $< ..."
	@mkdir -p $(@D)
	@$(VENV_DIR)/bin/pospell -l "$(LANGUAGE)" -p dict $< > $@ || true

$(LOGS_DIR)/pospell-$(NOW)/all.txt:
	@echo "Gathering all typos in $(LOGS_DIR)/pospell-$(NOW)/all.txt ..."
	@cut -d: -f3- $(DESTS) | sort -u > $@


# merge: Merge translations from BRANCH (Python version currently aim of
#        translation) into each branch listed by BUGFIXBRANCH and
#        OLDERBRANCHES (branches of older Python versions) so that older
#        versions of the Python Docs try make at least some use of the latest
#        translations. OLDERBRANCHES has '--no-overwrite' flag so it does not
#        overwrite translated strings, preserving history.
#        After merging, only commit and push only if any file was git-added
#        (staged) to the target branch; otherwise, it does nothing.
merge: venv $(BUGFIXBRANCH) $(OLDERBRANCHES)

$(OLDERBRANCHES):  OVERWRITEFLAG = --no-overwrite
$(BUGFIXBRANCH) $(OLDERBRANCHES):
	@if [[ $@ == $(BRANCH) ]]; then \
	    echo "Ignoring attempt to pomerge '$(BRANCH)' into itself."; \
	else \
	    echo "Merging translations from $(BRANCH) branch into $@ ..."; \
	    $(VENV_DIR)/bin/pomerge --from-files *.po **/*.po; \
	    git checkout $@; \
	    $(VENV_DIR)/bin/pomerge $(OVERWRITEFLAG) --to-files *.po **/*.po; \
	    $(VENV_DIR)/bin/powrap --modified *.po **/*.po; \
	    git add -u; \
	    if [ -n "$(git diff --name-only --cached)" ]; then \
	        git commit -m $(MSG); \
	        git push; \
	    else \
	        echo 'Nothing to commit'; \
	    fi; \
	    git checkout $(BRANCH); \
	fi


# lint: Report reStructuredText syntax errors in the translation files
lint: venv
	@mkdir -p "$(LOGS_DIR)"
	@$(VENV_DIR)/bin/sphinx-lint *.po **/*.po |& \
	    tee -a $(LOGS_DIR)/lint-$(NOW).txt || true
	@echo "Lint output stored in $(LOGS_DIR)/lint-$(NOW).txt"


# 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.
clean:
	rm -rf "$(VENV_DIR)"
	rm -rf "$(CPYTHON_DIR)/$(LOCALE_DIR)"
	[ -d "$(CPYTHON_DIR)" ] && $(MAKE) -C "$(CPYTHON_DIR)/Doc" clean-venv