makersgc/upython

Edición de la documentación de Micropython de Asociación Python Canarias

upython's Issues

Organizar ejemplos y ejercicios en directorios separados

Si los códigos que se utilizan como ejemplos y para los ejercicios se organizasen en directorios separados estarían más accesibles a aquellos que quieran ir directos a uno concreto; e incluso ejecutarlo si el interesado ha clonado el repositorio. De lo contrario, tendría que buscar en el README lo que le interesa. Además, en el caso de que el README cambie y se sustituyan algunos ejemplos u ejercicios por otros, sus códigos quedarían almacenados en sus respectivas carpetas.

Para ello propongo:

• Copiar los códigos de los ejercicios a archivos independientes en el directorio ejercicios.
• Copiar los códigos de los ejemplos a archivos independientes en el directorio ejemplos.
• Revisar los códigos para ajustarlos al PEP8.

Generar documentación a partir de Sphinx/MkDocs y Read the Docs/GitHub Pages/Netlify

Hace un tiempo se habló en el grupo de Telegram de makersGC sobre la posibilidad de generar un sitio web con esta documentación que estamos generando. Nunca llegamos a culminar esa discusión con acciones, pero creo que sería muy interesante para la comunidad maker, especialmente la de micropython, y no solo la de Gran Canaria.

Por ello les propongo aquí discutir esto. Existen diferentes servicios y herramientas que podríamos utilizar. Para generar la documentación:

• Sphinx, para formatos Markdown y reStructuredText.
• MkDocs, solo para Markdown.

Para alojar la documentación se me han ocurrido los siguientes servicios:

• Read the Docs. La URL sería del tipo https://PROYECTO.readthedocs.io/en/master, donde PROYECTO podría ser upython o upython-es.
• GitHub Pages. La URL sería https://makersgc.github.io/upython. Este nos empuja un poco a tener aunque sea una página del tipo portada informativa en la url makersgc.github.io.
• Netlify. La URL sería del tipo https://palabras-aleatorias-identificadorNumerico.netlify.com (por ej., esta que utilizo para un proyecto que tengo: https://affectionate-hypatia-0ab213.netlify.com/).

Mi opinión

Obviamente, las tres opciones nos permiten utilizar un dominio propio y personalizar la URL. Aunque he trabajado más con GitHub Pages, he de admitir que últimamente he empezado a trastear mucho con Netlify para un proyecto (ivanhercaz/buruma) y lo cierto es que me gusta mucho como funciona. La página se podría desplegar cada vez que se realice un cambio en este repositorio, sin necesidad de estar ejecutando comandos específicos ni nada por el estilo. Solo tendría que realizarse la configuración del despliegue del repositorio en Netlify.

¿Qué opinan ustedes?

CC. @kerberosdelhades, @franksosa.

P. S. Siéntanse libres de invitar a cualquiera a esta discusión y de animar a los miembros del grupo de Telegam a participar. Por mi parte, lo haré si puedo, pero estoy usando un móvil un poco escacharrado mientras el mío está en el taller...