Skip to content

Commit 18fc9bf

Browse files
mgaitanmgaitan
committed
Merge remote-tracking branch 'upstream/3.8' into faq_general
2 parents ad83082 + e1049f2 commit 18fc9bf

File tree

506 files changed

+53191
-32823
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

506 files changed

+53191
-32823
lines changed

‎.gitignore

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,64 @@
11
*.mo
2+
/_build/
3+
4+
# Submodules to avoid issues
5+
cpython
6+
.migration/tutorialpyar
7+
8+
# Files overriden by our scripts
9+
Doc/tools/templates/customsourcelink.html
10+
Doc/tools/templates/indexsidebar.html
11+
Doc/CONTRIBUTING.rst
12+
Doc/translation-memory.rst
13+
Doc/upgrade-python-version.rst
14+
locales/
15+
16+
# Byte-compiled / optimized / DLL files
17+
__pycache__/
18+
*.py[cod]
19+
20+
# C extensions
21+
*.so
22+
23+
# Distribution / packaging
24+
venv
25+
.Python
26+
env/
27+
build/
28+
develop-eggs/
29+
dist/
30+
downloads/
31+
eggs/
32+
lib/
33+
lib64/
34+
parts/
35+
sdist/
36+
var/
37+
*.egg-info/
38+
.installed.cfg
39+
*.egg
40+
.mypy_cache/
41+
42+
# PyInstaller
43+
# Usually these files are written by a python script from a template
44+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
45+
*.manifest
46+
*.spec
47+
48+
# Installer logs
49+
pip-log.txt
50+
pip-delete-this-directory.txt
51+
52+
# Unit test / coverage reports
53+
htmlcov/
54+
.tox/
55+
.coverage
56+
.cache
57+
nosetests.xml
58+
coverage.xml
59+
60+
# Ides
61+
.vscode/
62+
.idea/
63+
/translation-memory.po
64+
/locale/

‎.gitmodules

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[submodule "cpython"]
2+
path = cpython
3+
url = https://github.com/python/cpython.git
4+
branch = 3.8
5+
shallow = true
6+
[submodule "tutorialpyar"]
7+
path = .migration/tutorialpyar
8+
url = https://github.com/pyar/tutorial.git

‎.migration/rst2po.py

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# rst2po.py
2+
# Script to migrate the Python official tutorial that we have already translated in PyAr
3+
# (https://github.com/PyAr/tutorial) from reStructuredText to the new official translation format (.po)
4+
#
5+
# It parses the .rst and compare sentence/paragraph by sentence/paragraph and if the match is exact,
6+
# and there is no translation for that sentence/paragraph it updates the .po file with the translated text
7+
# from the .rst file.
8+
9+
import re
10+
import glob
11+
import os
12+
import polib # fades
13+
14+
15+
PO_DIR = os.path.abspath(
16+
os.path.join(
17+
os.path.dirname(__file__),
18+
'..',
19+
))
20+
21+
RST_TRADUCIDOS_DIR = os.path.abspath(
22+
os.path.join(
23+
os.path.dirname(__file__),
24+
'tutorialpyar',
25+
'traducidos',
26+
))
27+
28+
RST_ORIGINAL_DIR = os.path.abspath(
29+
os.path.join(
30+
os.path.dirname(__file__),
31+
'tutorialpyar',
32+
'original',
33+
))
34+
35+
36+
37+
def get_rst_file(pofilename):
38+
"""Given a .po filename returns the corresponding .rst filename"""
39+
basename = os.path.basename(pofilename)
40+
basename, ext = basename.rsplit('.', 1)
41+
rstfilename = os.path.join(RST_TRADUCIDOS_DIR, f'{basename}.rst')
42+
if os.path.exists(rstfilename):
43+
return rstfilename
44+
45+
46+
def get_rst_original_filename(rstfilename):
47+
rst_original_filename = ''
48+
if rstfilename.endswith('real-index.rst'):
49+
rst_original_filename = 'index.rst'
50+
51+
basename = os.path.basename(rst_original_filename or rstfilename)
52+
rst_original_filename = os.path.join(RST_ORIGINAL_DIR, basename)
53+
if os.path.exists(rst_original_filename):
54+
return rst_original_filename
55+
56+
57+
def create_english_spanish_sentences(rstfilename):
58+
"""Create a tuple of (english, spanish) sentences for rstfilename"""
59+
60+
def get_paragraph(fd):
61+
lines = []
62+
paragraph = []
63+
for line in fd.read().splitlines():
64+
# import pdb; pdb.set_trace()
65+
if any([
66+
line.startswith('.. '),
67+
line.startswith('==='),
68+
line.startswith('---'),
69+
line.startswith('***'),
70+
]):
71+
continue
72+
73+
if line == '' and not paragraph:
74+
continue
75+
76+
if line == '':
77+
lines.append(' '.join(paragraph))
78+
paragraph = []
79+
continue
80+
paragraph.append(line)
81+
82+
return lines
83+
84+
# NOTE: we could use docutils and parse the rst in the correct way, but
85+
# that will probably take more time
86+
with open(get_rst_original_filename(rstfilename)) as fd:
87+
english = get_paragraph(fd)
88+
89+
with open(rstfilename) as fd:
90+
spanish = get_paragraph(fd)
91+
92+
result = list(zip(english, spanish))
93+
return result
94+
95+
96+
def get_rst_translation_text(rstfilename, english_spanish, text):
97+
"""Given an rstfilename an a text returns the corresponding translated text if exists"""
98+
for en, es in english_spanish:
99+
if en.replace("!", "") == text.replace("!", ""):
100+
return es
101+
102+
103+
def update_po_translation(pofilename, english, spanish):
104+
"""Update the pofilename with the translated spanish text"""
105+
pass
106+
107+
108+
for pofilename in glob.glob(PO_DIR + '**/*/*.po'):
109+
translated = False
110+
rstfilename = get_rst_file(pofilename)
111+
if rstfilename is None:
112+
continue
113+
114+
english_spanish = create_english_spanish_sentences(rstfilename)
115+
116+
po = polib.pofile(pofilename)
117+
for entry in po:
118+
english_text = entry.msgid
119+
spanish_text = entry.msgstr
120+
if spanish_text:
121+
# Do not override already translated text
122+
continue
123+
124+
translated_text = get_rst_translation_text(rstfilename, english_spanish, english_text)
125+
if translated_text is None:
126+
continue
127+
128+
translated = True
129+
130+
entry.msgstr = translated_text
131+
# update_po_translation(po, english_text, translated_text)
132+
133+
if translated:
134+
po.save(pofilename)

‎.migration/tutorialpyar

Submodule tutorialpyar added at e2b1222

‎.overrides/CONTRIBUTING.rst

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
:orphan:
2+
3+
Guía para contribuir en la traducción
4+
=====================================
5+
6+
¡Muchas gracias por tu interés en participar de la traducción de la documentación oficial de Python al Español!
7+
Necesitamos *mucho* de tu ayuda para poder seguir adelante con este proyecto.
8+
9+
.. note::
10+
11+
Si tienes cualquier duda, puedes enviarnos un email a docs-es@python.org.
12+
13+
14+
#. Crea un fork del repositorio_.
15+
16+
.. note::
17+
18+
Puedes consular la `ayuda oficial de GitHub`_, si lo deseas.
19+
20+
#. Clona el fork del repositorio que acabas de crear::
21+
22+
git clone git@github.com:<TU-USUARIO>/python-docs-es.git
23+
24+
#. Ingresa en la carpeta que `git clone` creó en tu computadora::
25+
26+
cd python-docs-es/
27+
28+
#. Agrega el repositorio original como "upstream"::
29+
30+
git remote add upstream https://github.com/pycampes/python-docs-es.git
31+
32+
#. Crea una rama nueva en base al artículo en el que vayas a trabajar.
33+
Por ejemplo, si vas a trabajar en el archivo ``glosario.po``, usa un nombre similar a::
34+
35+
git checkout -b traduccion-glosario
36+
37+
#. Una vez que hayas elegido el archivo, lo puedes abrir con el editor poedit_ y empezar a traducir.
38+
39+
#. Cuando hayas terminado tu sesión, debes guardar tus cambios y enviarlos a GitHub de nuevo::
40+
41+
git commit -am 'Traducido archivo {nombre de archivo}'
42+
git push origin traduccion-glosario
43+
44+
#. No olvides añadir tu nombre al archivo ``TRANSLATORS`` si no lo has hecho todavía.
45+
Los nombres se encuentran ordenados alfabéticamente por apellido.
46+
47+
#. Luego ve a tu página de GitHub y propone hacer un *Pull Request*.
48+
49+
.. note::
50+
51+
Puedes consultar la `ayuda oficial de GitHub para crear un Pull Request`_ si lo deseas.
52+
53+
54+
¿Qué archivo traducir?
55+
----------------------
56+
57+
Tenemos una `lista de issues en GitHub`_ en dónde vamos coordinando el trabajo realizado para no traducir dos veces lo mismo.
58+
El proceso para traducir un archivo es el siguiente:
59+
60+
61+
#. Elige cualquier de los que *no están asignados* a otra persona.
62+
#. Deja un comentario en el issue diciendo que quieres trabajar en él.
63+
#. Espera a que un administrador te asigne el issue.
64+
#. ¡Empieza a traducir!
65+
66+
67+
68+
A tener en cuenta
69+
-----------------
70+
71+
* No debes traducir el contenido de ``:ref:...`` y ``:term:...``.
72+
* Si tienes que palabras en inglés debes ponerlas en *italics* (rodeadas por asteriscos)
73+
* Si traduces un título que es un link, por favor traduce el link también (por ejemplo un artículo a Wikipedia).
74+
En caso de que no haya una traducción del artículo en Wikipedia deja el título sin traducir.
75+
* Tenemos una `Memoria de Traducción`_, que usamos para tener consistencia con algunos términos.
76+
77+
78+
79+
.. note::
80+
81+
También puedes unirte a `nuestro canal de Telegram`_ si necesitas ayuda.
82+
83+
84+
Previsualizar los cambios
85+
-------------------------
86+
87+
Hay dos formas de visualizar, junto con el resultado final de la documentación, los cambios que has hecho.
88+
89+
Read the Docs
90+
`````````````
91+
92+
Una vez que hayas hecho un Pull Request en GitHub, este mostrará al final de página una sección de "check".
93+
Allí debería haber uno que diga ``docs/readthedocs.org:python-docs-es`` y al lado un link de "Details".
94+
95+
Haciendo click en ese link verás una versión de la documentación con tus cambios.
96+
97+
Construcción local
98+
``````````````````
99+
100+
Desde el mismo directorio ``python-docs-es/`` que se creó cuando hiciste ``git clone`` puedes ejecutar::
101+
102+
make build
103+
104+
Este comando demorará unos minutos y generará toda la documentación en formato HTML en tu computadora.
105+
Puedes ver el resultado con tu navegador de internet (Firefox, Chrome, etc) ejecutando::
106+
107+
make serve
108+
109+
Y luego accediendo a http://localhost:8000/
110+
111+
112+
.. _repositorio: https://github.com/PyCampES/python-docs-es
113+
.. _ayuda oficial de GitHub: https://help.github.com/es/github/getting-started-with-github/fork-a-repo
114+
.. _ayuda oficial de GitHub para crear un Pull Request: https://help.github.com/es/github/collaborating-with-issues-and-pull-requests/about-pull-requests
115+
.. _poedit: https://poedit.net/
116+
117+
.. _nuestro canal de Telegram: https://t.me/python_docs_es
118+
.. _Memoria de traducción: https://python-docs-es.readthedocs.io/page/translation-memory.html
119+
.. _lista de issues en GitHub: https://github.com/PyCampES/python-docs-es/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc

‎.overrides/README.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Overrides
2+
=========
3+
4+
This directory is recursively copied into `cpython/Doc`.
5+
It needs to have the same structure than `cpython/Doc`.
6+
7+
It allows us
8+
9+
- to have our own `CONTRIBUTING.rst` guide
10+
- change the index sidebar with links that are interesting for translators
11+
- etc

‎.overrides/progress.rst

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
:orphan:
2+
3+
===========================
4+
Progreso de la traducción
5+
===========================
6+
7+
Aquí puedes ver a la lista de todos los archivo de la documentación,
8+
con sus respectivos porcentajes de lo traducido, los párrafos marcados como ``fuzzy``,
9+
y otras estadísticas.
10+
11+
.. note::
12+
13+
Esta lista se actualiza automáticamente cuando Pull Requests se *mergean* a la rama ``3.8``.
14+
15+
.. runblock:: console
16+
17+
$ potodo --offline --path .

‎.overrides/tools/templates/customsourcelink.html

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{%- if show_source and has_source and sourcename %}
2+
<div role="note" aria-label="source link">
3+
<h3>{{ _('This Page') }}</h3>
4+
<ul class="this-page-menu">
5+
<li><a href="{{ pathto('bugs') }}">{% trans %}Report a Bug{% endtrans %}</a></li>
6+
<li>
7+
<a href="https://github.com/PyCampES/python-docs-es/blob/{{ version }}/{{ sourcename|replace('.rst.txt', '.po') }}"
8+
rel="nofollow">{{ _('Show Source') }}
9+
</a>
10+
</li>
11+
</ul>
12+
</div>
13+
{%- endif %}

‎.overrides/tools/templates/indexsidebar.html

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<h3>¡Ayúdanos a traducir!</h3>
2+
<ul>
3+
<li><a href="CONTRIBUTING.html">Guía para contribuir</a></li>
4+
<li><a href="progress.html">Progreso de la traducción</a></li>
5+
</ul>
6+
7+
<h3>Recursos</h3>
8+
<ul>
9+
<li><a href="https://mail.python.org/mailman3/lists/docs-es.python.org/">Lista de correos</a></li>
10+
<li><a href="https://t.me/python_docs_es">Canal de Télegram</a></li>
11+
<li><a href="https://github.com/PyCampES/python-docs-es">Repositorio GitHub</a></li>
12+
</ul>

0 commit comments

Comments
 (0)