Merge pull request #15 from stsewd/pagina-colaborar

Página de colaboración
pythonecuador · May 14, 2018 · c467de8 · c467de8
2 parents b806375 + 1fe9db8
commit c467de8
Show file tree

Hide file tree

Showing 2 changed files with 192 additions and 147 deletions.
diff --git a/README.md b/README.md
@@ -4,140 +4,7 @@ Código fuente del sitio de Python Ecuador
 
 # Colaborar
 
-Pull requests son bienvenidos! Recién estamos empezando,
-así que hay mucho por hacer.
+Puedes ver nuestra guía en <https://python.ec/guias/colaborar/>.
 
-Puedes mirar en los issues abiertos para buscar tareas por hacer <https://github.com/PythonEcuador/PythonEcuador.github.io/issues>
-(siempre asegúrate que alguien más no esté haciendo ya la tarea, así no gastamos esfuerzos).
-
-También puedes ayudar revisando pull requests <https://github.com/PythonEcuador/PythonEcuador.github.io/pulls>
-(la opinión de todos en bienvenida, pero siempre haciéndolo con respeto).
-
-_**No sé programar o no me siento mucha confianza para empezar**_:
-No todas las tareas involucran código,
-simples correcciones ortográficas también aportan al proyecto.
-Y si no te atreves a hacer la corrección por ti misma/o,
-puedes [crear un issue](https://github.com/PythonEcuador/PythonEcuador.github.io/issues/new) indicando el problema
-
-## Ejecutar el proyecto localmente
-
-Si tienes dudas y/o problemas mientras sigues los pasos,
-no dudes en preguntar en [nuestro canal de Telegram](https://t.me/pythonecuador).
-
-### Python
-
-Este proyecto usa Python 3, así que asegúrate de tenerlo instalado en tu sistema.
-Puedes descargarlo desde <https://www.python.org/downloads/>.
-Para verificar que tienes Python 3 en tu sistema ejecuta el siguiente comando en una terminal
-(ventana de comandos).
-
-```bash
-python --version
- Python 3.6.5
-```
-
-Si la salida del comando es diferente, no te preocupes, sólo debes asegurarte que el primer número sea un `3`.
-En caso que la salida haya sido algo como `2.7.14`, intenta con el comando `python3 --version`.
-
-En caso que ambos comandos te den un error o no sea la versión adecuada,
-asegúrate que Python esté en tun `PATH` o instala la versión adecuada.
-
-En los pasos siguientes usaremos el comando `python`,
-si el resultado de los pasos anteriores tuviste éxito haciéndolo con `python3`, debes usar ese comando.
-
-### Obteniendo el proyecto
-
-El proyecto está bajo el sistema de control de versiones git y alojado en GitHub,
-puedes descargar git desde <https://git-scm.com/download>.
-
-Haz un fork del proyecto desde GitHub (presionando el botón `Fork` en la parte superior).
-
-Ejecuta el siguiente comando en una terminal (ventana de comandos)
-para obtener el código. Donde `{tu-usuario}` es tu usuario de GitHub.
-
-```bash
-git clone https://github.com/{tu-usuario}/PythonEcuador.github.io.git
-```
-
-Entra al directorio que contiene el código fuente con
-
-```bash
-cd PythonEcuador.github.io
-```
-
-### Ejecutando el proyecto
-
-El sitio está construido usando [Nikola](https://getnikola.com),
-(no es necesario que sepas usarlo o que te leas toda la documentación para empezar a colaborar en el proyecto).
-
-Antes de instalar Nikola, es recomendable que crees un entorno virtual para Python
-(este paso debes hacerlo sólo una vez).
-
-```bash
-python -m venv venv
-```
-
-Ahora necesitamos activar el entorno virtual
-(este paso debes hacerlo cada vez que abras un nuevo terminal/ventana de comandos)
-
-```bash
-# Para sistemas Linux y Mac
-source venv/bin/activate
-# Para sistemas Windows
-venv\Scripts\activate
-```
-
-Ahora ya podemos instalar Nikola y otras dependencias
-
-```bash
-pip install -r requirements.txt
-```
-
-Finalmente, para ejecutar el sitio con Nikola
-
-``` bash
-nikola build
-nikola serve
-```
-
-Si abres un navegador e ingresas a <http://127.0.0.1:8000/> podrás ver el sitio.
-
-## Realizando cambios en el proyecto
-
-Una vez que tengas un [issue](https://github.com/PythonEcuador/PythonEcuador.github.io/issues) con cual trabajar.
-Crea una nueva rama con un nombre relacionado al issue que estás resolviendo.
-`arregla-issue-13` es el nombre de la rama usada en este ejemplo.
-
-```bash
-git checkout -b arregla-issue-13
-```
-
-Haz los cambios que sean pertinentes para arreglar el issue.
-Puedes ver los cambios en tu navegador mientras editas los archivos con el siguiente comando
-
-```bash
-nikola auto
-```
-
-Trata de hacer un commit para cada bloque de cambios relacionados que hagas
-
-```
-git add archivo-editado.rst
-git commit -m "Arreglada falta ortográfica"
-```
-
-Una vez que hayas hechos todos los cambios necesarios, súbelos a tu fork
-
-```
-git push -u origin
-```
-
-Dirígete a la página del proyecto <https://github.com/PythonEcuador/PythonEcuador.github.io>
-y verás un mensaje sugiriéndote hacer un pull request (PR).
-En la descripción del PR describe brevemente los cambios que hiciste.
-Espera a que un miembro de la comunidad revise tu PR,
-si son necesarios más cambios, los puedes hacer en la misma rama
-y repetir el proceso de agregar más commits y subiendo tus cambios con `git push`,
-tus cambios serán actualizados en el PR que ya abriste inicialmente.
-Si no hay más cambios y tu PR es aprobada, sólo debes esperar a que un miembro de la comunidad
-haga un merge.
+¿404? El sitio aún no está en línea, mientras tanto puedes chequear la guía en
+<https://github.com/PythonEcuador/PythonEcuador.github.io/blob/src/pages/guias/colaborar.rst>.
diff --git a/pages/guias/colaborar.rst b/pages/guias/colaborar.rst
@@ -5,17 +5,195 @@
 .. link: 
 .. description: 
 .. type: text
-.. template: ayuda.tmpl
+.. template: pagina.tmpl
 
-Esta página debe contener la guía que está en
-https://github.com/PythonEcuador/PythonEcuador.github.io/blob/src/README.md
-además remover ese contenido del ``README`` y agregar un link a esta página.
+Colaborar
+---------
 
-Además se debe explicar la estructura del proyecto
-(qué cosa está en cada directorio y los archivos más importantes).
-Con una tabla de los nombres con una pequeña descripción bastaría.
+¡Pull requests son bienvenidos! Recién estamos empezando,
+así que hay mucho por hacer.
 
-Si es necesario se debe ser más explicativo en la guía y
-agregar enlaces a recursos que puedan servir para apraeder sobre
-determinados temas (git, reStructuredText, etc) en lo posible los
-recursos deberán estar en español y lo más actualizados posible.
+Puedes mirar en los `issues abiertos <https://github.com/PythonEcuador/PythonEcuador.github.io/issues>`_
+para buscar tareas por hacer
+(siempre asegúrate que alguien más no esté haciendo ya la tarea, así no gastamos esfuerzos).
+
+También puedes ayudar `revisando pull requests <https://github.com/PythonEcuador/PythonEcuador.github.io/pulls>`_
+(la opinión de todos es bienvenida, pero siempre haciéndolo con respeto).
+
+**No sé programar o no me siento con mucha confianza para empezar**
+No todas las tareas involucran código,
+simples correcciones ortográficas también aportan al proyecto.
+Y si no te atreves a hacer la corrección por ti misma/o,
+puedes al menos `crear un issue <https://github.com/PythonEcuador/PythonEcuador.github.io/issues/new>`_ indicando el problema.
+
+Ejecutar el proyecto localmente
+-------------------------------
+
+Si tienes dudas y/o problemas mientras sigues los pasos,
+no dudes en preguntar en `nuestro canal de Telegram <https://t.me/pythonecuador>`_.
+
+Python
+######
+
+Este proyecto usa Python 3, así que asegúrate de tenerlo instalado en tu sistema.
+Puedes descargarlo desde https://www.python.org/downloads/.
+Para verificar que tienes Python 3 en tu sistema ejecuta el siguiente comando en una terminal
+(ventana de comandos).
+
+.. code:: bash
+
+   python --version
+   Python 3.6.5
+
+Si la salida del comando es diferente, no te preocupes, sólo debes asegurarte que el primer número sea un ``3``.
+En caso que la salida haya sido algo como ``2.7.14``, intenta con el comando ``python3 --version``.
+
+En caso que ambos comandos te den un error o no sea la versión adecuada,
+asegúrate que Python esté en tu ``PATH`` o instala la versión adecuada.
+
+.. note::
+
+   En los pasos siguientes usaremos el comando ``python``,
+   si el resultado de los pasos anteriores tuviste éxito haciéndolo con ``python3``,
+   debes usar ese comando.
+
+Obteniendo el proyecto
+######################
+
+El proyecto está bajo el sistema de control de versiones git y alojado en GitHub,
+puedes descargar git desde https://git-scm.com/download.
+
+Haz un fork del proyecto desde GitHub (presionando el botón ``Fork`` en la parte superior del proyecto).
+
+Ejecuta el siguiente comando en una terminal (ventana de comandos)
+para obtener el código. Donde ``{tu-usuario}`` es tu usuario de GitHub.
+
+.. code:: bash
+
+   git clone https://github.com/{tu-usuario}/PythonEcuador.github.io.git
+
+Entra al directorio que contiene el código fuente con
+
+.. code:: bash
+   
+   cd PythonEcuador.github.io
+
+Ejecutando el proyecto
+######################
+
+El sitio está construido usando `Nikola <https://getnikola.com>`_.
+(no es necesario que sepas usarlo o que te leas toda la documentación para empezar a colaborar en el proyecto).
+
+Antes de instalar Nikola, es recomendable que crees un entorno virtual para Python
+(este paso debes hacerlo sólo una vez).
+
+.. code:: bash
+
+   python -m venv venv
+
+Ahora necesitamos activar el entorno virtual
+(este paso debes hacerlo cada vez que abras un nuevo terminal/ventana de comandos)
+
+.. code:: bash
+
+   # Para sistemas Linux y Mac
+   source venv/bin/activate
+
+   # Para sistemas Windows
+   venv\Scripts\activate
+
+Ahora ya podemos instalar Nikola y otras dependencias
+
+.. code:: bash
+
+   pip install -r requirements.txt
+
+Finalmente, para ejecutar el sitio con Nikola
+
+.. code:: bash
+   
+   nikola build
+   nikola serve
+
+Si abres un navegador e ingresas a http://127.0.0.1:8000/ podrás ver el sitio.
+
+Realizando cambios en el proyecto
+#################################
+
+Una vez que tengas un `issue <https://github.com/PythonEcuador/PythonEcuador.github.io/issues>`_ con cual trabajar.
+Crea una nueva rama con un nombre relacionado al issue que estás resolviendo.
+`arregla-issue-13` es el nombre de la rama usada en este ejemplo.
+
+.. code:: bash
+
+   git checkout -b arregla-issue-13
+
+Haz los cambios que sean pertinentes para arreglar el issue.
+Puedes ver los cambios en tu navegador mientras editas los archivos con el siguiente comando
+
+.. code:: bash
+
+   nikola auto
+
+Trata de hacer un commit por cada bloque de cambios relacionados que hagas
+
+.. code:: bash
+
+   git add archivo-editado.rst
+   git commit -m "Arreglada falta ortográfica"
+
+Una vez que hayas hechos todos los cambios necesarios, súbelos a tu fork
+
+.. code:: bash
+
+   git push -u origin
+
+Dirígete a la página del proyecto https://github.com/PythonEcuador/PythonEcuador.github.io
+y verás un mensaje sugiriéndote hacer un pull request (PR).
+En la descripción del PR describe brevemente los cambios que hiciste.
+
+Espera a que un miembro de la comunidad revise tu PR,
+si son necesarios más cambios, los puedes hacer en la misma rama
+y repetir el proceso de agregar más commits y subiendo tus cambios con ``git push``,
+tus cambios serán actualizados en el PR que ya abriste inicialmente.
+Si no hay más cambios y tu PR es aprobada, sólo debes esperar a que un miembro de la comunidad haga un merge.
+
+Estructura del proyecto
+-----------------------
+
+files/
+  Archivos generales del sitio
+pages/
+  Aquí están todas las páginas del sitio
+posts/
+  Posts del sitio
+themes/custom/
+  Tema personalizado del sitio
+themes/custom/assets/
+  Javascript, css, etc
+themes/custom/templates/
+  Aquí están los templates; son archivos parecidos a html reutilizables
+conf.py
+  En este archivo están las configurariones del sitio
+
+Editar una página incompleta
+----------------------------
+
+Si te topaste con una página con el título *¡Esta sección necesita de tu ayuda!*,
+para empezar a editarla debes localizar esta página (se encuentran en el directorio ``pages/``)
+cada archivo corresponde a la URL de la página, estos archivos son del formato reStructuredText.
+
+¡Pero ahí no está toda la página que vi en el navegador! Ya vamos a esa parte.
+
+Como podrás notar, al principio del archivo, se encutran metadatos. Como:
+
+- ``title``: El título de la página
+- ``slug``: El path del URL
+- ``template``: El template a ser usado para la página
+
+Existen otros, pero esos son los más relevantes, sobre todo el de template.
+Por defecto estará en ``ayuda.tmpl``, tu primer paso será cambiarlo por ``pagina.tmpl``.
+Estos templates contienen el contenido base de la página (se encuentran en ``themes/custom/templates/``).
+Y los archivos ``.rst`` sólo contienen el texto principal.
+
+Ahora sólo necesitas editar el archivos ``.rst`` ¡y listo!