|
1 | | -# Makefile for es Python Documentation |
2 | 1 | # |
3 | | -# Here is what you can do: |
| 2 | +# Makefile for Spanish Python Documentation |
| 3 | +# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
4 | 4 | # |
5 | | -# - make # Automatically build an html local version |
6 | | -# - make todo # To list remaining tasks |
7 | | -# - make merge # To merge pot from upstream |
8 | | -# - make fuzzy # To find fuzzy strings |
9 | | -# - make progress # To compute current progression |
10 | | -# - make upgrade_venv # To upgrade the venv that compiles the doc |
| 5 | +# based on: https://github.com/python/python-docs-pt-br/blob/3.8/Makefile |
11 | 6 | # |
12 | | -# Modes are: autobuild-stable, autobuild-dev, and autobuild-html, |
13 | | -# documented in gen/src/3.6/Doc/Makefile as we're only delegating the |
14 | | -# real work to the Python Doc Makefile. |
15 | | - |
16 | | -CPYTHON_CLONE := ../cpython/ |
17 | | -SPHINX_CONF := $(CPYTHON_CLONE)/Doc/conf.py |
18 | | -LANGUAGE := es |
19 | | -VENV := ~/.venvs/python-docs-i18n/ |
20 | | -PYTHON := $(shell which python3) |
21 | | -MODE := html |
22 | | -BRANCH = 3.7 |
23 | | -COMMIT = |
24 | | -JOBS = auto |
25 | | - |
26 | | - |
27 | | -.PHONY: all |
28 | | -all: $(SPHINX_CONF) $(VENV)/bin/activate |
29 | | -ifneq "$(shell cd $(CPYTHON_CLONE) 2>/dev/null && git describe --contains --all HEAD)" "$(BRANCH)" |
30 | | - $(warning "Your ../cpython checkout may be on the wrong branch, got $(shell cd $(CPYTHON_CLONE) 2>/dev/null && git describe --contains --all HEAD) expected $(BRANCH)") |
31 | | -endif |
32 | | - mkdir -p $(CPYTHON_CLONE)/locales/$(LANGUAGE)/ |
33 | | - ln -nfs $(shell $(PYTHON) -c 'import os; print(os.path.realpath("."))') $(CPYTHON_CLONE)/locales/$(LANGUAGE)/LC_MESSAGES |
34 | | - $(MAKE) -C $(CPYTHON_CLONE)/Doc/ VENVDIR=$(VENV) PYTHON=$(PYTHON) SPHINXOPTS='-qW -j$(JOBS) -D locale_dirs=../locales -D language=$(LANGUAGE) -D gettext_compact=0 -D latex_engine=xelatex -D latex_elements.inputenc= -D latex_elements.fontenc=' $(MODE) |
35 | | - |
36 | | - |
37 | | -$(SPHINX_CONF): |
38 | | - git clone --depth 1 --branch $(BRANCH) https://github.com/python/cpython.git $(CPYTHON_CLONE) |
39 | | - [ -n "$(COMMIT)" ] && (i=1; while ! $$(git -C $(CPYTHON_CLONE) checkout $(COMMIT)); do i=$$((i * 2)); git -C $(CPYTHON_CLONE) fetch --depth $$i; done) || true |
40 | | - |
41 | | - |
42 | | -.PHONY: upgrade_venv |
43 | | -upgrade_venv: |
44 | | - $(MAKE) -C $(CPYTHON_CLONE)/Doc/ VENVDIR=$(VENV) PYTHON=$(PYTHON) venv |
45 | | - |
46 | | - |
47 | | -$(VENV)/bin/activate: |
48 | | - $(MAKE) -C $(CPYTHON_CLONE)/Doc/ VENVDIR=$(VENV) PYTHON=$(PYTHON) venv |
49 | | - |
50 | | - |
51 | | -.PHONY: progress |
52 | | -progress: |
53 | | - @python3 -c 'import sys; print("{:.1%}".format(int(sys.argv[1]) / int(sys.argv[2])))' \ |
54 | | - $(shell msgcat *.po */*.po | msgattrib --translated | grep -c '^msgid') \ |
55 | | - $(shell msgcat *.po */*.po | grep -c '^msgid') |
56 | | - |
57 | | - |
58 | | -.PHONY: merge |
59 | | -merge: upgrade_venv |
60 | | -ifneq "$(shell cd $(CPYTHON_CLONE) 2>/dev/null && git describe --contains --all HEAD)" "$(BRANCH)" |
61 | | - $(error "You're merging from a different branch:" "$(shell cd $(CPYTHON_CLONE) 2>/dev/null && git describe --contains --all HEAD)" vs "$(BRANCH)") |
62 | | -endif |
63 | | - (cd $(CPYTHON_CLONE)/Doc; rm -f build/NEWS) |
64 | | - (cd $(CPYTHON_CLONE); $(VENV)/bin/sphinx-build -Q -b gettext -D gettext_compact=0 Doc pot/) |
65 | | - find $(CPYTHON_CLONE)/pot/ -name '*.pot' |\ |
66 | | - while read -r POT;\ |
67 | | - do\ |
68 | | - PO="./$$(echo "$$POT" | sed "s#$(CPYTHON_CLONE)/pot/##; s#\.pot\$$#.po#")";\ |
69 | | - mkdir -p "$$(dirname "$$PO")";\ |
70 | | - if [ -f "$$PO" ];\ |
71 | | - then\ |
72 | | - case "$$POT" in\ |
73 | | - *whatsnew*) msgmerge --backup=off --force-po --no-fuzzy-matching -U "$$PO" "$$POT" ;;\ |
74 | | - *) msgmerge --backup=off --force-po -U "$$PO" "$$POT" ;;\ |
75 | | - esac\ |
76 | | - else\ |
77 | | - msgcat -o "$$PO" "$$POT";\ |
78 | | - fi\ |
79 | | - done |
80 | | - |
81 | | - |
82 | | -.PHONY: fuzzy |
83 | | -fuzzy: |
84 | | - for file in *.po */*.po; do echo $$(msgattrib --only-fuzzy --no-obsolete "$$file" | grep -c '#, fuzzy') $$file; done | grep -v ^0 | sort -gr |
| 7 | + |
| 8 | +# Configuration |
| 9 | + |
| 10 | +CPYTHON_PATH := cpython #Current commit for this upstream repo is setted by the submodule |
| 11 | +BRANCH := 3.7 |
| 12 | +LANGUAGE_TEAM := python-docs-es |
| 13 | +LANGUAGE := es |
| 14 | + |
| 15 | +# Internal variables |
| 16 | +VENV := $(shell realpath ./venv) |
| 17 | +PYTHON := $(shell which python3) |
| 18 | +WORKDIRS := $(VENV)/workdirs |
| 19 | +CPYTHON_WORKDIR := $(WORKDIRS)/cpython |
| 20 | +LOCALE_DIR := $(WORKDIRS)/locale |
| 21 | +JOBS := auto |
| 22 | +SPHINXERRORHANDLING := "-W" |
| 23 | +TRANSIFEX_PROJECT := python-newest |
| 24 | +POSPELL_TMP_DIR := .pospell |
| 25 | + |
| 26 | + |
| 27 | +.PHONY: help |
| 28 | +help: |
| 29 | + @echo "Please use 'make <target>' where <target> is one of:" |
| 30 | + @echo " build Build an local version in html, with warnings as errors" |
| 31 | + @echo " push Update translations and Transifex config in the repository" |
| 32 | + @echo " pull Download translations from Transifex; calls 'venv'" |
| 33 | + @echo " tx-config Recreate an up-to-date project .tx/config; calls 'pot'" |
| 34 | + @echo " pot Create/Update POT files from source files" |
| 35 | + @echo " serve Serve a built documentation on http://localhost:8000" |
| 36 | + @echo " spell Check spelling, storing output in $(POSPELL_TMP_DIR)" |
| 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 from Transifex'; \ |
| 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, and apply line wrapping. |
| 84 | +# For downloading new translation files, first run "tx-config" target |
| 85 | +# to update the translation file mapping. |
| 86 | +.PHONY: pull |
| 87 | +pull: venv |
| 88 | + $(VENV)/bin/tx pull --force --language=$(LANGUAGE) --parallel |
| 89 | + $(VENV)/bin/powrap --quiet *.po **/*.po |
| 90 | + |
| 91 | + |
| 92 | +# tx-config: After running "pot", create a new Transifex config file by |
| 93 | +# reading pot files generated, then tweak this config file to |
| 94 | +# LANGUAGE. |
| 95 | +.PHONY: tx-config |
| 96 | +tx-config: pot |
| 97 | + cd $(CPYTHON_WORKDIR)/Doc/locales; \ |
| 98 | + rm -rf .tx; \ |
| 99 | + $(VENV)/bin/sphinx-intl create-txconfig; \ |
| 100 | + $(VENV)/bin/sphinx-intl update-txconfig-resources \ |
| 101 | + --transifex-project-name=$(TRANSIFEX_PROJECT) \ |
| 102 | + --locale-dir . \ |
| 103 | + --pot-dir pot; |
| 104 | + |
| 105 | + cd $(OLDPWD) |
| 106 | + mv $(CPYTHON_WORKDIR)/Doc/locales/.tx/config .tx/config |
| 107 | + |
| 108 | + sed -i .tx/config \ |
| 109 | + -e '/^source_file/d' \ |
| 110 | + -e 's|<lang>/LC_MESSAGES/||' \ |
| 111 | + -e "s|^file_filter|trans.$(LANGUAGE)|" |
| 112 | + |
| 113 | + |
| 114 | +# pot: After running "setup" target, run a cpython Makefile's target |
| 115 | +# to generate .pot files under $(CPYTHON_WORKDIR)/Doc/locales/pot |
| 116 | +.PHONY: pot |
| 117 | +pot: setup |
| 118 | + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc/ \ |
| 119 | + VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \ |
| 120 | + PYTHON=$(PYTHON) \ |
| 121 | + ALLSPHINXOPTS='-E -b gettext \ |
| 122 | + -D gettext_compact=0 \ |
| 123 | + -d build/.doctrees . \ |
| 124 | + locales/pot' \ |
| 125 | + build |
| 126 | + |
| 127 | + |
| 128 | +# setup: After running "venv" target, prepare that virtual environment with |
| 129 | +# a local clone of cpython repository and the translation files. |
| 130 | +# If the directories exists, only update the cpython repository and |
| 131 | +# the translation files copy which could have new/updated files. |
| 132 | +.PHONY: setup |
| 133 | +setup: venv |
| 134 | + # Setup the main clone |
| 135 | + git submodule sync |
| 136 | + git submodule update --init --force $(CPYTHON_PATH) |
| 137 | + # Setup the current work directory |
| 138 | + if ! [ -d $(CPYTHON_WORKDIR) ]; then \ |
| 139 | + rm -fr $(WORKDIRS); \ |
| 140 | + mkdir -p $(WORKDIRS); \ |
| 141 | + git clone $(CPYTHON_PATH) $(CPYTHON_WORKDIR); \ |
| 142 | + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc \ |
| 143 | + VENVDIR=$(CPYTHON_WORKDIR)/Doc/venv \ |
| 144 | + PYTHON=$(PYTHON) venv; \ |
| 145 | + fi |
| 146 | + |
| 147 | + # Setup translation files |
| 148 | + if ! [ -d $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ ]; then \ |
| 149 | + mkdir -p $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/; \ |
| 150 | + fi; \ |
| 151 | + cp --parents *.po **/*.po $(LOCALE_DIR)/$(LANGUAGE)/LC_MESSAGES/ \ |
| 152 | + |
| 153 | + |
| 154 | +# venv: create a virtual environment which will be used by almost every |
| 155 | +# other target of this script |
| 156 | +.PHONY: venv |
| 157 | +venv: |
| 158 | + if [ ! -d $(VENV) ]; then \ |
| 159 | + $(PYTHON) -m venv --prompt $(LANGUAGE_TEAM) $(VENV); \ |
| 160 | + fi |
| 161 | + |
| 162 | + $(VENV)/bin/python -m pip install -q -r requirements.txt 2> $(VENV)/pip-install.log |
| 163 | + |
| 164 | + if grep -q 'pip install --upgrade pip' $(VENV)/pip-install.log; then \ |
| 165 | + $(VENV)/bin/pip install -q --upgrade pip; \ |
| 166 | + fi |
| 167 | + |
| 168 | + |
| 169 | +# serve: serve the documentation in a simple local web server, using cpython |
| 170 | +# Makefile's "serve" target. Run "build" before using this target. |
| 171 | +.PHONY: serve |
| 172 | +serve: |
| 173 | + $(MAKE) -C $(CPYTHON_WORKDIR)/Doc serve |
| 174 | + |
| 175 | + |
| 176 | +# list files for spellchecking |
| 177 | +SRCS := $(wildcard *.po **/*.po) |
| 178 | +DESTS = $(addprefix $(POSPELL_TMP_DIR)/out/,$(patsubst %.po,%.txt,$(SRCS))) |
| 179 | + |
| 180 | + |
| 181 | +# spell: run spell checking tool in all po files listed in SRCS variable, |
| 182 | +# storing the output in text files DESTS for proofreading. The |
| 183 | +# DESTS target run the spellchecking, while the typos.txt target |
| 184 | +# gather all reported issues in one file, sorted without redundancy |
| 185 | +.PHONY: spell |
| 186 | +spell: venv $(DESTS) $(POSPELL_TMP_DIR)/typos.txt |
| 187 | + |
| 188 | +$(POSPELL_TMP_DIR)/out/%.txt: %.po dict |
| 189 | + @echo "Checking $< ..." |
| 190 | + @mkdir -p $(@D) |
| 191 | + @$(VENV)/bin/pospell -l $(LANGUAGE) -p dict $< > $@ || true |
| 192 | + |
| 193 | +$(POSPELL_TMP_DIR)/typos.txt: |
| 194 | + @echo "Gathering all typos in $(POSPELL_TMP_DIR)/typos.txt ..." |
| 195 | + @cut -d: -f3- $(DESTS) | sort -u > $@ |
| 196 | + |
| 197 | + |
| 198 | +# clean: remove all .mo files and the venv directory that may exist and |
| 199 | +# could have been created by the actions in other targets of this script |
| 200 | +.PHONY: clean |
| 201 | +clean: |
| 202 | + rm -fr $(VENV) |
| 203 | + rm -rf $(POSPELL_TMP_DIR) |
| 204 | + find -name '*.mo' -delete |
0 commit comments