|
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 | | -forfilein*.po*/*.po;doecho$$(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.txt2>$(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 |