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</p>
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</p>

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</p>

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</p>

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</p>

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</p>

Comparación de Opciones

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

Opción	Descripción	Ejemplo
`-o`	Especifica el nombre del archivo de salida.	`ibis ... -o mi_documento.pdf`
`-d`	Especifica el directorio de salida.	`ibis ... -d /ruta/a/mi/directorio`
`-b`	Especifica una rama o etiqueta específica.	`ibis ... -b mi_rama`
`-l`	Usa un directorio local en lugar de un repositorio remoto.	`ibis -l /ruta/a/mi/repositorio`
`--help`	Muestra todas las opciones disponibles.	`ibis --help`
Sin opciones	Crea un PDF con el nombre del repositorio.	`ibis https://github.com/usuario/repositorio`
Directorio actual	El PDF se guarda en el directorio actual.
`nombre_repo.pdf`	Nombre del archivo PDF generado por defecto.
`pipx`	Forma recomendada de instalación.	`pipx install ibis-next`
`ibis`	Comando principal para generar el PDF.	`ibis https://github.com/usuario/repositorio`
URL de GitHub	Especifica el repositorio remoto de la documentación.	`ibis https://github.com/usuario/repositorio`
Sin opciones	Especifica el nombre del archivo de salida.	`ibis https://github.com/usuario/repositorio -o mi_documento.pdf`

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</p>
- 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

Categorías: Desarrollo

Etiquetas: