Ayuda de MicroPython 1.14 o 1.XX en archivo pdf. Cómo lo obtuve sin los errores de compilación usando su GitHub y alguna mejora que he implementado.

 

   Buenas a tod@s. Estaba revisando y buscando la última ayuda actualizada de MicroPython (https://docs.micropython.org/en/latest/), ya que tengo varias placas STM32 que lo utilizan. Además de la ayuda en la web, en formato html, me interesaba tenerla en pdf, y en un solo fichero. Así que después de mucho indagar...

   Me di de cuenta que en la web se podía descargar el archivo pdf de la documentación, pero mi sorpresa fue  que las últimas versiones (v1.13, v1.14 o posteriores) no estaba disponible, los enlaces dan error y pensé yo qué raro. Bueno después de mirar el GitHub de MicroPython (https://github.com/micropython/micropython) hay una carpeta docs/ en donde está "todo" para poder generar la documentación desde tu computadora. Recomiendo leer el archivo de texto README.md que te explica más o menos como generar los ficheros de ayuda. Yo lo intenté desde Linux, en concreto desde la distribución Ubuntu 18.04.5 LTS, instalando los paquetes de latex necesarios, sphinx y sphinx_rtd_theme para poder generar la ayuda, Python 3. Después a través del comando git clono el repositorio en una carpeta en mi computadora y luego desde una terminal dentro del directorio doc/ ejecuto el comando: make latexpdf en una terminal, para comenzar con la generación de la ayuda del archivo MicroPython.pdf. Aquí ya empezamos con los problemas. Una captura vale más que mil palabras. 😅 Pincha en la imagen para verla más grande:

   

   Decir que hay que estar conectado a Internet para hacer bien el proceso. En la captura se puede ver como no se pudo descargar 3 imágenes (son 3 warnings). Estos warnings tienen que ver con sphinix, no con LaTex. No soy un experto en los dos pero se usar Google 😁  Bueno, ejecuto el comando make latexpdf desde la terminal, y aunque genere se generen errores y los warnings se genera el fichero MicroPython.tex. y sus ficheros auxiliares para generar un archivo pdf. Después me descargo de la web las imágenes que faltan ya que los enlaces web están bien y las coloco en el directorio build/latex/ , edito el archivo MicroPython.tex con los enlaces a los ficheros de las imágenes y hago para que aparezcan centradas, corrijo un error en el fichero que sale el carácter de la letra griega omega mayúscula (Ω) y la cambio por el código de LaTex: $\Omega$. Y por último compilo manualmente el fichero tex poniendo en la terminal el siguiente comando desde el directorio build/latex/: make all-pdf ya que existe otro Makefile dentro de ese directorio. Obteniendo, por fin, nuestro ansiado  MicroPython.pdf.

   Comentaros que aunque he resumido aquí todo el proceso, no es tan trivial hacer todo esto, lleva su tiempo de estudio, averiguaciones y manejarse en Linux. Yo sé algo git, de LaTex, de usar make pero no de sphinix. Busqué primero por Google sobre estos errores, y al parecer en un foro dicen que los desarrolladores están en fase de solucionarlo, pero me parece que no debe de ser fácil, porque este error lleva tiempo, desde 2020 me imagino por las fechas de los ficheros pdf de ayuda anteriores que sí se generaron.

   Así que aquí, por fin, os dejo los archivos pdf de toda la ayuda de MicroPython versión 1.14, generado el 1 de Abril de 2021, y posteriores versiones que vaya generando en unos enlaces para que lo podáis descargar. Ojo, que puede haber una versión más moderna de la ayuda ya que los desarrolladores van actualizando cosas, incluso dentro de la misma versión de MicroPython. Así que para estar a la última, tendríamos que actualizar nuestra copia del repositorio local y realizar el mismo proceso de nuevo. Pincha en la imagen para verla más grande:

    Enlaces de descarga:

• MicroPython_v1.14_Documentation.pdf
• MicroPython_v1.17_Documentation.pdf
  

   Si te he ayudado, como mínimo agradécelo y si te animas, un donativo de material o económico me vendría muy bien. Me ayudarías a generar más contenido interesante.

    Hasta pronto.