Cómo crear un PDF con documentación en formato rst desde GitHub usando Ibis-Next

Ibis-Next es una herramienta que crea archivos PDF a partir de documentación escrita en formato reStructuredText (rst). Puedes usarla directamente en repositorios de GitHub, como por ejemplo en el repositorio symfony-docs.

Aquí te enseñamos cómo hacerlo de manera sencilla.

Instalación

Primero, instala Ibis-Next en tu sistema. La forma recomendada es usar pipx:

pipx install ibis-next

Si no tienes pipx, primero instala pipx:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Si sigues teniendo errores baja hasta el Troubleshooting

Creando la documentación PDF

Una vez instalado, genera el PDF con el comando ibis seguido de la URL del repositorio en GitHub. Por ejemplo, para el repositorio symfony-docs, ejecuta:

ibis-next https://github.com/symfony/symfony-docs

Esto creará un archivo PDF llamado symfony-docs.pdf en tu directorio actual.

Personalizar la Salida

Ibis-Next permite personalizar el nombre del archivo de salida y el directorio donde se guarda.

Cambiar el nombre del archivo

Usa la opción -o para especificar un nombre de archivo diferente:

ibis https://github.com/symfony/symfony-docs -o documentacion_symfony.pdf

Cambiar el directorio de salida

Usa la opción -d para especificar un directorio de salida:

ibis https://github.com/symfony/symfony-docs -d /ruta/a/tu/directorio

Opciones Adicionales

Ibis-Next tiene varias opciones que permiten controlar el proceso de generación del PDF.

Listar todas las opciones

Ejecuta ibis --help para ver todas las opciones disponibles.

Especificar una rama o etiqueta

Usa la opción -b para especificar una rama o etiqueta específica:

ibis https://github.com/symfony/symfony-docs -b nombre_de_la_rama

Usar un directorio local

Si ya tienes una copia local del repositorio, puedes usar la opción -l para generar el PDF desde ese directorio:

ibis -l /ruta/a/tu/repositorio/local

Comparación de Opciones

Aquí hay una tabla que resume las opciones más importantes:

Troubleshooting

Otra opción es instalarlo con composer

composer require hi-folks/ibis-next

Precisará de varios paquetes según el error:

Your requirements could not be resolved to an installable set of packages.

Problem 1
- hi-folks/ibis-next[v1.0.0, …, v1.0.10] require mpdf/mpdf ^8.0 -> satisfiable by mpdf/mpdf[v8.0.0, …, v8.2.5].
- hi-folks/ibis-next[v1.0.11, …, v1.2.0, v2.0.0, …, v2.0.6] require ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
- mpdf/mpdf[v8.0.0, …, v8.0.3] require php ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0 || ~7.3.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.0.4, …, v8.0.7] require php ^5.6 || ~7.0.0 || ~7.1.0 || ~7.2.0 || ~7.3.0 || ~7.4.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.0.8, …, v8.0.9] require php ^5.6 || ^7.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.0.10, …, v8.0.12] require php ^5.6 || ^7.0 || ~8.0.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.0.13, …, v8.1.2] require php ^5.6 || ^7.0 || ~8.0.0 || ~8.1.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.1.3, …, v8.2.0] require php ^5.6 || ^7.0 || ~8.0.0 || ~8.1.0 || ~8.2.0 -> your php version (8.3.6) does not satisfy that requirement.
- mpdf/mpdf[v8.2.1, …, v8.2.5] require ext-gd * -> it is missing from your system. Install or enable PHP's gd extension.
- Root composer.json requires hi-folks/ibis-next * -> satisfiable by hi-folks/ibis-next[v1.0.0, …, v1.2.0, v2.0.0, …, v2.0.6].

o enable extensions, verify that they are enabled in your .ini files:
- /etc/php/8.3/cli/php.ini
- /etc/php/8.3/cli/conf.d/10-opcache.ini
- /etc/php/8.3/cli/conf.d/10-pdo.ini
- /etc/php/8.3/cli/conf.d/20-calendar.ini
- /etc/php/8.3/cli/conf.d/20-ctype.ini
- /etc/php/8.3/cli/conf.d/20-curl.ini
- /etc/php/8.3/cli/conf.d/20-exif.ini
- /etc/php/8.3/cli/conf.d/20-ffi.ini
- /etc/php/8.3/cli/conf.d/20-fileinfo.ini
- /etc/php/8.3/cli/conf.d/20-ftp.ini
- /etc/php/8.3/cli/conf.d/20-gettext.ini
- /etc/php/8.3/cli/conf.d/20-iconv.ini
- /etc/php/8.3/cli/conf.d/20-intl.ini
- /etc/php/8.3/cli/conf.d/20-mbstring.ini
- /etc/php/8.3/cli/conf.d/20-phar.ini
- /etc/php/8.3/cli/conf.d/20-posix.ini
- /etc/php/8.3/cli/conf.d/20-readline.ini
- /etc/php/8.3/cli/conf.d/20-shmop.ini
- /etc/php/8.3/cli/conf.d/20-sockets.ini
- /etc/php/8.3/cli/conf.d/20-sysvmsg.ini
- /etc/php/8.3/cli/conf.d/20-sysvsem.ini
- /etc/php/8.3/cli/conf.d/20-sysvshm.ini
- /etc/php/8.3/cli/conf.d/20-tokenizer.ini
- /etc/php/8.3/cli/conf.d/20-zip.ini

En estos momentos la versión mpdf no es compatible con php 8.3, toca cambiar la versión en el composer:

composer require "mpdf/mpdf:^8.2.1"

despues de ejecutar ese require , regresa:

 Problem 1
- mpdf/mpdf[v8.2.1, …, v8.2.5] require ext-gd * -> it is missing from your system. Install or enable PHP's gd extension.
- Root composer.json requires mpdf/mpdf ^8.2.1 -> satisfiable by mpdf/mpdf[v8.2.1, …, v8.2.5].

que resolvemos instalando gd:

sudo apt-get install php-gd

Edita el archivo php.ini y asegúrate de que la línea extension=gd esté descomentada (sin punto y coma al principio).

y finalmente reiniciar apache2:

sudo systemctl restart apache2

bash: ./vendor/bin/ibis-next: No existe el archivo o el directorio

Ejecutar en el directorio:

composer require hi-folks/ibis-next