Skip to content

Commit eb96cb7

Browse files
rffontenellerffontenelle
committed
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.
1 parent dd83ae4 commit eb96cb7

File tree

4 files changed

+270
-0
lines changed

4 files changed

+270
-0
lines changed

‎.github/workflows/pythonpackage.yml‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
name: Build and update Documentation
2+
3+
# Daily at 0 am
4+
#on:
5+
# schedule:
6+
# - cron: '0 0 * * *'
7+
8+
jobs:
9+
build:
10+
11+
runs-on: ubuntu-latest
12+
strategy:
13+
max-parallel: 4
14+
matrix:
15+
python-version: [3.7]
16+
17+
steps:
18+
- uses: actions/checkout@v2
19+
with:
20+
ref: 3.8
21+
- run: |
22+
git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/*
23+
24+
- name: Set up Python ${{ matrix.python-version }}
25+
uses: actions/setup-python@v1
26+
with:
27+
python-version: ${{ matrix.python-version }}
28+
29+
- name: Install dependencies via package manager
30+
run: |
31+
sudo apt update
32+
sudo apt install -y gettext
33+
34+
- name: Prepare virtual environment
35+
run: |
36+
make venv
37+
venv/bin/pip --version
38+
venv/bin/tx --version
39+
venv/bin/sphinx-intl --help
40+
41+
- name: If failed, make the log file an artifact
42+
if: failure()
43+
uses: actions/upload-artifact@v1
44+
with:
45+
name: pip-install-log
46+
path: venv/pip-install.log
47+
48+
- name: Recreate an up-to-date project .tx/config
49+
run: |
50+
make tx-config
51+
52+
- name: Update translations from Transifex
53+
run: |
54+
if [[ -n "$TRANSIFEX_APIKEY" ]]; then
55+
echo -e "[https://www.transifex.com]\n" \
56+
"api_hostname = https://api.transifex.com\n" \
57+
"hostname = https://www.transifex.com\n" \
58+
"password = $TRANSIFEX_APIKEY\n" \
59+
"username = api" \
60+
> ~/.transifexrc
61+
fi
62+
make pull
63+
git status --short
64+
env:
65+
TRANSIFEX_APIKEY: ${{ secrets.TRANSIFEX_APIKEY }}
66+
67+
- name: Build documentation
68+
run: |
69+
make build CPYTHON_PATH=/tmp/cpython/ SPHINXERRORHANDLING=''
70+
71+
- name: Push translations
72+
run: |
73+
git config user.email "github-actions[bot]@users.noreply.github.com"
74+
git config user.name "github-actions[bot]"
75+
make push
76+
env:
77+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
78+
79+
- name: Build documentation treating warnings as errors
80+
run: |
81+
make build CPYTHON_PATH=/tmp/cpython/

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
*.mo
2+
.tx/**/*.po
3+
venv/

‎Makefile‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
#
2+
# Makefile for Brazilian Portuguese Python Documentation
3+
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4+
#
5+
# based on: https://github.com/python/python-docs-fr/blob/3.8/Makefile
6+
#
7+
8+
# Configuration
9+
10+
CPYTHON_PATH := ../cpython
11+
BRANCH := 3.8
12+
LANGUAGE_TEAM := python-docs-pt-br
13+
LANGUAGE := pt_BR
14+
15+
# Internal variables
16+
17+
UPSTREAM := https://github.com/python/cpython
18+
VENV := $(shell realpath ./venv)
19+
PYTHON := $(shell which python3)
20+
WORKDIRS := $(VENV)/workdirs
21+
CPYTHON_WORKDIR := $(WORKDIRS)/cpython
22+
LOCALE_DIR := $(WORKDIRS)/locale
23+
JOBS := auto
24+
SPHINXERRORHANDLING := "-W"
25+
TRANSIFEX_PROJECT := python-newest
26+
27+
28+
.PHONY: help
29+
help:
30+
@echo "Please use 'make <target>' where <target> is one of:"
31+
@echo " build Build an local version in html, with warnings as errors"
32+
@echo " push Update translations and Transifex config in the repository"
33+
@echo " pull Download translations from Transifex; calls 'venv'"
34+
@echo " tx-config Recreate an up-to-date project .tx/config; calls 'pot'"
35+
@echo " pot Create/Update POT files from source files"
36+
@echo " serve Serve a built documentation on http://localhost:8000"
37+
@echo ""
38+
39+
40+
# build: build the documentation using the translation files currently available
41+
# at the moment. For most up-to-date docs, run "tx-config" and "pull"
42+
# before this. If passing SPHINXERRORHANDLING='', warnings will not be
43+
# treated as errors, which is good to skip simple Sphinx syntax mistakes.
44+
.PHONY: build
45+
build: setup
46+
$(MAKE) -C $(CPYTHON_WORKDIR)/Doc/ \
47+
VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \
48+
PYTHON=$(PYTHON) \
49+
SPHINXERRORHANDLING=$(SPHINXERRORHANDLING) \
50+
SPHINXOPTS='-q --keep-going -j$(JOBS) \
51+
-D locale_dirs=$(LOCALE_DIR) \
52+
-D language=$(LANGUAGE) \
53+
-D gettext_compact=0 \
54+
-D latex_engine=xelatex \
55+
-D latex_elements.inputenc= \
56+
-D latex_elements.fontenc=' \
57+
html;
58+
59+
@echo "Success! Open file://$(CPYTHON_WORKDIR)/Doc/build/html/index.html, " \
60+
"or run 'make serve' to see them in http://localhost:8000";
61+
62+
63+
# push: push new translation files and Transifex config files to repository,
64+
# if any. Do nothing if there is no file changes. If GITHUB_TOKEN is set,
65+
# then assumes we are in GitHub Actions, requiring different push args
66+
.PHONY: push
67+
push:
68+
if ! git status -s | egrep '\.po|\.tx/config'; then \
69+
echo "Nothing to commit"; \
70+
exit 0; \
71+
else \
72+
git add *.po **/*.po .tx/config; \
73+
git commit -m 'Update translations'; \
74+
if [ $(GITHUB_TOKEN) != "" ]; then \
75+
header="$(echo -n token:"$(GITHUB_TOKEN)" | base64)"; \
76+
git -c http.extraheader="AUTHORIZATION: basic $(header)" push; \
77+
else \
78+
git push; \
79+
fi; \
80+
fi
81+
82+
83+
# pull: Download translations files from Transifex. For downloading new
84+
# translation files, first run "tx-config" target to update the
85+
# translation file mapping.
86+
.PHONY: pull
87+
pull: venv
88+
$(VENV)/bin/tx pull --force --language=$(LANGUAGE) --parallel
89+
90+
91+
# tx-config: After running "pot", create a new Transifex config file by
92+
# reading pot files generated, then tweak this config file to
93+
# LANGUAGE.
94+
.PHONY: tx-config
95+
tx-config: pot
96+
cd $(CPYTHON_WORKDIR)/Doc/locales; \
97+
rm -rf .tx; \
98+
$(VENV)/bin/sphinx-intl create-txconfig; \
99+
$(VENV)/bin/sphinx-intl update-txconfig-resources \
100+
--transifex-project-name=$(TRANSIFEX_PROJECT) \
101+
--locale-dir . \
102+
--pot-dir pot;
103+
104+
cd $(OLDPWD)
105+
mv $(CPYTHON_WORKDIR)/Doc/locales/.tx/config .tx/config
106+
107+
sed -i .tx/config \
108+
-e '/^source_file/d' \
109+
-e 's|<lang>/LC_MESSAGES/||' \
110+
-e "s|^file_filter|trans.$(LANGUAGE)|"
111+
112+
113+
# pot: After running "setup" target, run a cpython Makefile's target
114+
# to generate .pot files under $(CPYTHON_WORKDIR)/Doc/locales/pot
115+
.PHONY: pot
116+
pot: setup
117+
$(MAKE) -C $(CPYTHON_WORKDIR)/Doc/ \
118+
VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \
119+
PYTHON=$(PYTHON) \
120+
ALLSPHINXOPTS='-E -b gettext \
121+
-D gettext_compact=0 \
122+
-d build/.doctrees . \
123+
locales/pot' \
124+
build
125+
126+
127+
# setup: After running "venv" target, prepare that virtual environment with
128+
# a local clone of cpython repository and the translation files.
129+
# If the directories exists, only update the cpython repository and
130+
# the translation files copy which could have new/updated files.
131+
.PHONY: setup
132+
setup: venv
133+
# Setup the main clone
134+
if ! [ -d $(CPYTHON_PATH) ]; then \
135+
git clone --depth 1 --branch $(BRANCH) $(UPSTREAM) $(CPYTHON_PATH); \
136+
else \
137+
git -C $(CPYTHON_PATH) pull --rebase; \
138+
fi
139+
140+
# Setup the current work directory
141+
if ! [ -d $(CPYTHON_WORKDIR) ]; then \
142+
rm -fr $(WORKDIRS); \
143+
mkdir -p $(WORKDIRS); \
144+
git clone $(CPYTHON_PATH) $(CPYTHON_WORKDIR); \
145+
$(MAKE) -C $(CPYTHON_WORKDIR)/Doc \
146+
VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \
147+
PYTHON=$(PYTHON) venv; \
148+
fi
149+
150+
# Setup translation files
151+
if ! [ -d $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ ]; then \
152+
mkdir -p $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/; \
153+
fi; \
154+
cp --parents *.po **/*.po $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ \
155+
156+
157+
# venv: create a virtual environment which will be used by almost every
158+
# other target of this script
159+
.PHONY: venv
160+
venv:
161+
if [ ! -d $(VENV) ]; then \
162+
$(PYTHON) -m venv --prompt $(LANGUAGE_TEAM) $(VENV); \
163+
fi
164+
165+
$(VENV)/bin/python -m pip install -q -r requirements.txt 2> $(VENV)/pip-install.log
166+
167+
if grep -q 'pip install --upgrade pip' $(VENV)/pip-install.log; then \
168+
$(VENV)/bin/pip install -q --upgrade pip; \
169+
fi
170+
171+
172+
# serve: serve the documentation in a simple local web server, using cpython
173+
# Makefile's "serve" target. Run "build" before using this target.
174+
.PHONY: serve
175+
serve:
176+
$(MAKE) -C $(CPYTHON_WORKDIR)/Doc serve
177+
178+
179+
# clean: remove all .mo files and the venv directory that may exist and
180+
# could have been created by the actions in other targets of this script
181+
.PHONY: clean
182+
clean:
183+
rm -fr $(VENV)
184+
find -name '*.mo' -delete

‎requirements.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
transifex-client
2+
sphinx-intl

0 commit comments

Comments
 (0)