From 3079c2788df8b20e8afffd117ece42dbc090f192 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 13:24:49 +0200 Subject: [PATCH 1/6] Banner pointing people to the contributing guide to help us --- conf.py | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/conf.py b/conf.py index b5edfd203d..c11708b0a8 100644 --- a/conf.py +++ b/conf.py @@ -33,10 +33,33 @@ os.system('mkdir -p cpython/locales/es/') os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') +os.system('ln -nfs `pwd`/CONTRIBUTING.rst cpython/Doc/CONTRIBUTING.rst') gettext_compact = False locale_dirs = ['../locales', 'cpython/locales'] # relative to the sourcedir def setup(app): + + def add_contributing_banner(app, doctree): + """ + Insert a banner at the top of the index. + + This way, we can easily communicate people to help with the translation, + pointing them to different resources. + """ + from docutils import nodes, core + + message = '¡Ayúdanos a traducir la documentación oficial de Python al Español! ' \ + f'Más información en `Como contribuir `_' + + paragraph = core.publish_doctree(message)[0] + banner = nodes.warning(ids=['contributing-banner']) + banner.append(paragraph) + + for document in doctree.traverse(nodes.document): + document.insert(0, banner) + # Change the sourcedir programmatically because Read the Docs always call it with `.` app.srcdir = 'cpython/Doc' + + app.connect('doctree-read', add_contributing_banner) From 0e93e340e71b57af0ad33e574eff1685e7ff13d3 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 14:58:36 +0200 Subject: [PATCH 2/6] Update CONTRIBUTING.rst guide --- CONTRIBUTING.rst | 108 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 84 insertions(+), 24 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 20967622c1..ad2af76356 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,38 +1,98 @@ -Guía para contribuir en la documentación utilizando Github -=========================================================== +Guía para contribuir en la traducción +===================================== -Crea un fork y clona el repositorio ------------------------------------ +¡Muchas gracias por tu interés en participar de la traducción de la documentación oficial de Python al Español! +Necesitamos *mucho* de tu ayuda para poder seguir adelante con este proyecto. -https://help.github.com/en/github/getting-started-with-github/fork-a-repo +Actualmente se puede colaborar utilizando una de las dos siguientes formas que: -Luego de tener un fork clonalo en tu maquina +#. Utilizando el repositorio de GitHub y el editor poedit_ +#. Realizando traducciones directamente en Transifex -.. code-block:: bash - # Git clone your github fork using ssh (replace raulcd): - # Clona el repositorio en tu maquina ejecutando - git@github.com:/python-docs-es.git +.. note:: - # Ingresá al nuevo directorio con el repo - cd python-docs-es/ + Si tienes cualquier duda, puedes enviarnos un email a docs-es@python.org. - # Agregá el repositorio original como upstream. - git remote add upstream https://github.com/raulcd/python-docs-es.git +Desde GitHub +------------ -Crear un build local --------------------- +#. Crea un fork del repositorio. + + .. note:: + + Puedes consular la `ayuda oficial de GitHub`_, si lo deseas. + + .. _ayuda oficial de GitHub: https://help.github.com/es/github/getting-started-with-github/fork-a-repo + +#. Clona el repositorio:: + + git clone git@github.com:/python-docs-es.git + +#. Ingresa en la carpeta que `git clone` creó en tu computadora:: + + cd python-docs-es/ + +#. Agrega el repositorio original como "upstream":: + + git remote add upstream https://github.com/pycampes/python-docs-es.git + +#. Instala las herramientas de `pre-commit` (opcional):: + + pip install pre-commit + pre-commit install + +#. Mira que archivo necesita ser traducido. El siguiente comando te mostrará una lista de archivos y los porcentajes traducidos. + Elige uno que no esté completo:: + + make progress + +#. Una vez que hayas elegido el archivo, lo puedes abrir con el editor poedit_ y empezar a traducir. + +#. Cuando hayas terminado tu sesión, debes guardar tus cambios y enviarlos a GitHub de nuevo:: -Hay un script para automatizar estos pasos el mismo va a: + git commit -am 'Traducido archivo {nombre de archivo}' + git push origin update-translation -- Crear un virtualenv dentro del directorio del repositorio e instalar en el mismo las librearias necesarias -- Clonar el repositorio oficial de cpython para construir ("biuldear") la documentación. +#. Luego ve a tu página de GitHub y propone hacer un Pull Request -.. code-block:: bash + .. note:: - make build + Puedes consultar la `ayuda oficial de GitHub para crear un Pull Request`_ si lo deseas. + + .. _ayuda oficial de GitHub para crear un Pull Request: https://help.github.com/es/github/collaborating-with-issues-and-pull-requests/about-pull-requests + + +.. _poedit: https://poedit.net/ + + + +Previsualizar los cambios +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Hay dos formas de visualizar, junto con el resultado final de la documentación, los cambios que has hecho. + +Read the Docs +````````````` + +Una vez que hayas hecho un Pull Request en GitHub, este mostrará al final de página una sección de "check". +Ahí, debería haber uno que diga `docs/readthedocs.org:python-docs-es`, y al lado un link de "Details". +Haciendo click en ese link, deberías poder ver una versión de la documentación con tus cambios. + +Construcción local +`````````````````` + +Desde el mismo directorio `python-docs-es/` que se creó cuando hiciste `git clone`, puedes ejecutar:: + + make build + +Este comando demorará unos minutos y generará toda la documentación en formato HTML en tu computadora. +Puedes ver el resultado abriendo el archivo `venv/workdirs/cpython/Doc/build/html/index.html` +con tu navegador de internet (Firefox, Chrome, etc). + + +Utilizando Transifex +-------------------- - # luego para poder ver la documentación ejecuta el siguiente comando y podes luego ir a http://localhost:8000 para ver la documentación - # recién construida. - make serve +ToDo. From 2b9f2c5195cb0c42b4b43e1f9a962539692896c2 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 15:11:18 +0200 Subject: [PATCH 3/6] Remove pre-commit from normal steps --- CONTRIBUTING.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index ad2af76356..5a089e4185 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -38,11 +38,6 @@ Desde GitHub git remote add upstream https://github.com/pycampes/python-docs-es.git -#. Instala las herramientas de `pre-commit` (opcional):: - - pip install pre-commit - pre-commit install - #. Mira que archivo necesita ser traducido. El siguiente comando te mostrará una lista de archivos y los porcentajes traducidos. Elige uno que no esté completo:: From dbeb24ab13f08c26276317174bd505ede3906887 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 15:12:57 +0200 Subject: [PATCH 4/6] Render properly --- CONTRIBUTING.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5a089e4185..803f4782fe 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -28,15 +28,15 @@ Desde GitHub #. Clona el repositorio:: - git clone git@github.com:/python-docs-es.git + git clone git@github.com:/python-docs-es.git #. Ingresa en la carpeta que `git clone` creó en tu computadora:: - cd python-docs-es/ + cd python-docs-es/ #. Agrega el repositorio original como "upstream":: - git remote add upstream https://github.com/pycampes/python-docs-es.git + git remote add upstream https://github.com/pycampes/python-docs-es.git #. Mira que archivo necesita ser traducido. El siguiente comando te mostrará una lista de archivos y los porcentajes traducidos. Elige uno que no esté completo:: @@ -47,8 +47,8 @@ Desde GitHub #. Cuando hayas terminado tu sesión, debes guardar tus cambios y enviarlos a GitHub de nuevo:: - git commit -am 'Traducido archivo {nombre de archivo}' - git push origin update-translation + git commit -am 'Traducido archivo {nombre de archivo}' + git push origin update-translation #. Luego ve a tu página de GitHub y propone hacer un Pull Request From 140a98c8f02a71974be1344185cf566d1eb34ace Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 15:14:38 +0200 Subject: [PATCH 5/6] Update message --- conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index c11708b0a8..4bfbfffb59 100644 --- a/conf.py +++ b/conf.py @@ -50,7 +50,8 @@ def add_contributing_banner(app, doctree): from docutils import nodes, core message = '¡Ayúdanos a traducir la documentación oficial de Python al Español! ' \ - f'Más información en `Como contribuir `_' + f'Puedes encontrar más información en `Como contribuir `_ ' \ + 'y así ayudarnos a acercar Python a más personas de habla hispana.' paragraph = core.publish_doctree(message)[0] banner = nodes.warning(ids=['contributing-banner']) From 6c702bcd8cf4181969288414a1ebe6b91655df87 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Sun, 3 May 2020 15:31:33 +0200 Subject: [PATCH 6/6] Use make serve --- CONTRIBUTING.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 803f4782fe..731cb38fa9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -83,8 +83,11 @@ Desde el mismo directorio `python-docs-es/` que se creó cuando hiciste `git clo make build Este comando demorará unos minutos y generará toda la documentación en formato HTML en tu computadora. -Puedes ver el resultado abriendo el archivo `venv/workdirs/cpython/Doc/build/html/index.html` -con tu navegador de internet (Firefox, Chrome, etc). +Puedes ver el con tu navegador de internet (Firefox, Chrome, etc) ejecutando:: + + make serve + +Y luego accediendo a http://localhost:8000/ Utilizando Transifex