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

[ivanhercaz]

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...