Merge pull request #40 from PyCampES/contributing-banner

humitos · web-flow · commit 63ae3680c6e9 · 2020-05-03T15:37:04.000+02:00
diff --git 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:<TU_USUARIO>/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:<TU-USUARIO>/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
@@ -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 </es/{version}/CONTRIBUTING.html>`_  ' \
+        '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)
