diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 20967622c1..731cb38fa9 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,38 +1,96 @@ -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:: + + Si tienes cualquier duda, puedes enviarnos un email a docs-es@python.org. + + +Desde GitHub +------------ + +#. 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:: - # Ingresá al nuevo directorio con el repo cd python-docs-es/ - # Agregá el repositorio original como upstream. - git remote add upstream https://github.com/raulcd/python-docs-es.git +#. Agrega el repositorio original como "upstream":: + git remote add upstream https://github.com/pycampes/python-docs-es.git -Crear un build local --------------------- +#. 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:: + + 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 -Hay un script para automatizar estos pasos el mismo va a: + .. note:: -- 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. + Puedes consultar la `ayuda oficial de GitHub para crear un Pull Request`_ si lo deseas. -.. code-block:: bash + .. _ayuda oficial de GitHub para crear un Pull Request: https://help.github.com/es/github/collaborating-with-issues-and-pull-requests/about-pull-requests - make build - # 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 +.. _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 con tu navegador de internet (Firefox, Chrome, etc) ejecutando:: + + make serve + +Y luego accediendo a http://localhost:8000/ + + +Utilizando Transifex +-------------------- + +ToDo. diff --git a/conf.py b/conf.py index b5edfd203d..4bfbfffb59 100644 --- a/conf.py +++ b/conf.py @@ -33,10 +33,34 @@ 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'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']) + 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)