Logo del curso de programación de Ubuntu Touch

Para la documentación del curso he utilizado principalmente Markdown y GitBook. Markdown es un lenguaje de marcado, que permite con elementos sencillos, formatear un texto. Para ver el documento «generado» hace falta un visor o una herramienta que interprete el archivo y lo muestre en un formato más adecuado para el usuario. Por esta razón he usado GitBook para esta tarea. Como las necesidades cambian, ahora necesito tener más control sobre la documentación por lo que he pasado a otra herramienta llamada Sphinx.

Uno de los cambios afecta al idioma inicial. Hasta este momento tenía dos idiomas para el curso. EL principal era el español y es el que tiene más contenido publicado. El segundo idioma es el inglés. Con Sphinx el orden cambiará por razones prácticas. Es más sencillo tener el documento base en inglés y con la ayuda las herramientas de traducción, pasarlo a otros idiomas. Si lo hiciera al contrario y un usuario quisiera traducir el documento al francés debería conocer el español para hacerlo.

Aunque subiré la documentación generada en varios formatos a InnerZaurus, es posible que los más impacientes quieran ver el curso a medida que lo actualizo. Para estos usuarios voy a indicar los pasos que hay que seguir para compilar y generar la documentación. Os recuerdo que subiré el último viernes de cada mes la documentación actualizada en varios formatos (HTML, PDF y ePUB) a la Web de InnerZaurus.

Instalación de las dependencias

Mi entorno de trabajo es KDE Neon. Esta distribución toma como base Ubuntu y puede usar todos sus repositorios. Los comandos pueden variar en otras distribuciones. Normalmente los nombres de los paquetes son similares. Si tenéis cualquier duda para instalar las dependencias podéis decirlo en los comentarios.

Los paquetes básicos para generar la documentación en formato HTML son:

sudo apt-get install build-essential
sudo apt-get install python3-sphinx sphinxsearch python3-pip

Sphinx es la herramienta que se usa para generar la documentación. Es necesario instalar varios paquetes adicionales:

pip3 install sphinx-intl
pip3 install --upgrade recommonmark
pip3 install sphinx_rtd_theme

Pip es el gestor de paquetes que usa Python. En estos momentos hay dos versiones. Cuando un comando aparece como «pip» indica que es de Python 2.x. Si aparece «pip3» estamos con un comando de Python 3. En un mismo sistema podemos tener varias versiones de Python pero no conviene mezclarlas al generar la documentación. En el curso se usa Python 3 porque es la versión más reciente.

La documentación se puede generar en otros formatos usando herramientas intermedias. Lo interesante es que Sphinx se encarga de todo por nosotros si tenemos instaladas todas las herramientas. Para generar un archivo PDF se utiliza LaTeX. Es necesario instalar los siguientes paquetes:

sudo apt-get install texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended
sudo texlive-lang-english texlive-lang-spanish 

El formato ePUB no necesita instalar ninguna dependencia adicional para usarlo.

Descargar el código fuente del proyecto

El código fuente está formado por una serie de archivos que dicen al programa lo que tiene que hacer. Como servidor de control de versiones utilizo GitLab por varias razones. La primera es que permite tener proyectos de forma gratuita mientras que la segunda es que se puede instalar de forma local sin pagar licencias extras. Podemos tener un servidor local o virtual (VPS) e instalar GitLab en él. Hay varias versiones disponibles pero la versión comunitaria tiene todo lo necesario para la mayoría de los casos. Los paquetes mínimos para trabajar con Git son:

sudo apt-get install git git-cola

El control de versiones es Git. Git-cola es un interfaz gráfico para trabajar con Git. No voy a entrar ahora en detalle con el funcionamiento de Git. Dejo reservado este tema para un capítulo futuro en el curso.

cd Documentos
git clone https://gitlab.com/mimecar/qt-programming-course-sphinx.git

Se descargará el código fuente y lo dejará en la carpeta Documentos del usuario.

Descarga del repositorio

Una vez finalizado el proceso ya podemos compilar la documentación.

Compilación de la documentación

Como he comentado antes, la documentación del curso está en inglés. La razón es muy sencilla: facilita la traducción del inglés a otros idiomas. Si tomara como base el español, los usuarios que quisieran ayudar con la traducción deberían conocerlo para poder trabajar. Voy a comentar las dos formas de generar la documentación. La primera es la forma general y utiliza el idioma que tenga por defecto la documentación. Con la segunda conseguimos el mismo resultado forzando a que utilice un idioma concreto.

Todos los comandos se tienen que escribir en la carpeta raíz del repositorio.

make gettext
sphinx-intl update -p build/gettext -l es
make -e SPHINXOPTS="-D language='es'" html

Conclusiones

Al principio puede parecer un poco complicado usar Sphinx pero es razonablemente sencillo de usar. La documentación se puede generar de forma directa en inglés o añadiendo un par de opciones para generarla en castellano. En cualquier caso, es posible a futuro añadir un par de scripts al repositorio del código para automatizar más el proceso. Si tenéis cualquier duda podéis preguntarla en los comentarios o usando el grupo de Telegram del curso. https://t.me/curso_ubuntu_touch

0 comentarios

Dejar un comentario

¿Quieres unirte a la conversación?
Siéntete libre de contribuir!

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.