Guía para contribuir con tutoriales de p5.js

Invitamos a los educadores, colaboradores y entusiastas en general a contribuir con tutoriales de p5js. El proyecto de p5js hace que la programación creativa y el desarrollo de código abierto sean más accesibles para una comunidad diversa y estamos muy emocionados de publicar tutoriales sobre todos los aspectos del proceso de desarrollo. Nuestros materiales de aprendizaje hasta el momento incluyen guías sobre el aprendizaje de p5, la técnica de programación y cómo contribuir a un proyecto de código abierto.

Le damos la bienvenida a la contribución de nuevos tutoriales escritos y esta guía describe los pasos para proponer, preparar y contribuir con un tutorial.

Cómo empezar:

• Comprueba que el tema que hayas propuesto no haya sido cubierto antes. Puedes encontrar una lista aquí con los tutoriales que están en progreso. Si tu tema está marcado en esta lista como en progreso, tal vez puedes añadir al trabajo que se está llevando a cabo y cooperar preparando el trabajo ya existente para su publicación así que por favor contáctate con nosotros.
• Si tu tema no está cubierto y no está enlistado como en progreso, por favor escribe unas líneas sobre lo que propones cubrir y mándanos un email con esta descripción a [email protected].

Cómo preparar un tutorial de p5js para su publicación en línea:

Cuando tu tutorial esté listo para ser publicado, por favor sigue los siguientes pasos para preparar tu contenido para el sitio de p5js.

Guarda el contenido de tu tutorial en un archivo tutorial-name.hbs con esta estructura básica. Como se muestra en este archivo, tiene que contener un un encabezado como se muestra a continuación:

La carpeta que contiene tu tutorial se colocará en la carpeta 'tutoriales' del sitio de p5js. El archivo llamado index.hbs es la página de destino de los tutoriales de p5js, y el archivo test-tutorial.hbs es el tutorial de prueba.

Todos los contenidos deben de ir en las: <section > </section> etiquetas de la página, con el fórmato definido por las etiquetas <h1> y <h2> y las etiquetas de párrafo <p> como se muestra en la página del tutorial de prueba.

Si tu tutorial contiene imágenes, deben colocarse en la carpeta 'assets' del sitio p5, en la ubicación src / assets / learn / test-tutorial / images, como se muestra a continuación.

Para formatear correctamente el código en el html de la página, utiliza la etiqueta:

<pre><code class="language-javascript">
Your code here!
</code></pre>

Incorporar bosquejos p5.js

Usar p5js significa que puedes ilustrar tu tutorial con ejemplos de código animados, interactivos o editables para demostrar conceptos de programación. Tus ejemplos deben estar preparados como bosquejos p5.js y pueden ser incorporados en el tutorial de dos maneras.

1. Si el ejemplo es editable como en las páginas de referenciadel sitio de p5js, el bosquejo p5js debe ser incorporado en la página html usando el widget p5js. Sigue esta guía sobre cómo incorporar bosquejos p5js usando el widget escrito por Toolness. También puedes encontrar esto en la página del tutorial de prueba.
2. Si el ejemplo es animado y/o interactivo pero no editable, entonces el bosquejo p5js debe de ser incorporado en la página como un iframe como se describe a continuación.

Incorporar un bosquejo p5js usando un iframe

Un iframe es cómo crear una ventana a través de la cual puedes ver otra página, aislada del resto de tú página. En este caso va a ser una ventana al archivo index.html que contiene tu bosquejo p5js.

Coloca tus bosquejos p5 en la carpeta /src/assets/learn del sitio, en una carpeta etiquetada con el nombre de tu bosquejo como se muestra en la captura de pantalla. Aquí es donde todas las imágenes y bosquejos p5 enlazados por el iframe deben de estar guardados.

En las subcarpetas que contienen tus ejemplos p5 debe de haber un archivo sketch.js y otro embed.html para tu bosquejo.

Asegúrate que tu archivo embed.html tenga la ruta correcta hacia las librerías p5 del sitio. Si la estructura de tus archivos es igual a la de arriba, la ruta hacia las librerías p5 debe ser "../../../js/p5.min.js".

Una vez comprobado esto, ya puedes incorporar los archivos 'index' de p5js como iframes en el archivo .hbs que contiene el contenido de tu tutorial. El código de inserción para el iframe sería entonces:

<iframe src="http://p5js.org/assets/learn/tes-tutorial/embed.html" width="600" height="400">
</iframe>

Estilo para el iframe (esto podría directamente en la entrada o en una hoja de estilos):

<style> iframe{ border: none; } </style>

Aquí puedes explorar el bosquejo puro en ejecución:

Y aquí está incorporado en el sitio p5 usando el código a continuación:

Una cosa a recalcar es que necesitas ajustar manualmente el tamaño del iframe para que funcione de la mejor manera posible si las cosas son de tamaño estándar.

También nota que los enlaces a los archivos de las librerías de p5.js no provienen de la página con extensión .eps con todo el contenido del tutorial. En su lugar, van a estar localizados en la página html que está procesando tu bosquejo (en este caso se llama embed.html).

Más información sobre cómo incorporar bosquejos de p5.js se pueden encontrar aquí.

Los últimos detalles

Una vez que hayas terminado de escribir tu tutorial y tu contenido haya sido aprobado, copia (fork) desde GitHub el repositorio del sitio de p5.js, prepara tu contenido como lo hemos descrito anteriormente y finalmente crea una solicitud de (pull request) al repositorio del sitio de p5.js para que podamos agregar tu contenido y publicar tu contribución. ¡Felicidades!

¡Muchas gracias!