Procesando la documentación de Laravel 4 para mejor lectura o impresión

Introducción

Aún no me acostumbro a leer textos largos desde un PDF en el computador, en especial libros y manuales me gusta tenerlos impresos para resaltarlos y hacer anotaciones en ellos.  Por este motivo hice este script muy sencillo en PHP que obtiene las secciones del sitio web de la documentación de Laravel 4 y las une en un único documento que puede ser impreso o leído con mayor facilidad.

Documentación de Laravel 4

Requisitos

El único requisito para ejecutar el script es contar con el paquete de la interfaz de línea de comando de PHP (php-cli) instalado.

Ejecución

$ php laravel4.php

Al final la ejecución se encontrará el archivo output.html en el mismo directorio con la documentación generada.

Personalización

Si desea seleccionar cuales secciones de la documentación son finalmente incluidas durante la generación del documento, modifique la variable $urls (inicialmente comentada) definiendo en ella los URL de las respectivas secciones.  En caso de no definirse (por defecto) se tomarán automáticamente las secciones encontradas en la página en linea de la documentación.

También es posible modificar la presentación del documento resultante.  Para esto ajuste como se considere las clases CSS definidas en la plantilla en la función prepareTemplate.

Licenciamiento

Este script se distribuye bajo la licencia MIT.

Versiones

Recursos

Convirtiendo la documentación de FuelPHP a un único documento

Introducción.

FuelPHP es un framework para el desarrollo de aplicaciones que a pesar de su muy reciente aparición es muy interesante y prometedor para el entorno del desarrollo de aplicaciones web con software libre.  Este framework es similar a Codeigniter o Kohana en términos de su simplicidad, sin embargo no se basa directamente en ninguno de ellos sino que por el contario, toma los conceptos e ideas de diseño exitosas de los principales frameworks y los integra en una única base para la implementación de aplicaciones web.

Teniendo una relativa corta edad, su desarrollo ha sido veloz y su versión 1.0 se encuentra muy próxima a publicarse.  La documentación también ha evolucionado rápidamente y se encuentra en contínua actualización.  Esta se presenta por secciones que se pueden revisar directamente siendo esto muy apropiado para las consultas rápidas de la misma sin embargo -en mi opinión personal- no es tan útil cuando se está aprendiendo del framework por primera vez ya que no es posible realizar una revisión o búsqueda líneal de los temas ni mucho menos imprimirlos.

Dado lo prometedor del framework decidí tomarme un par de minutos para desarrollar una solución que me permitiera consolidar fácilmente la documentación en un único documento para poder imprimirlo y estudiar de él.  Terminé con una pequeña herramienta basada en Javascript con jQuery que realizar esta tarea.  Debido a las limitaciones de seguridad impuestas por los navegadores es necesario que se descargue en un servidor web local la documentación para que pueda ser procesada por esta herramienta.

Debe tenerse en cuenta que los documentos generados o impresos no recibirán las contínuas actualizaciones que si recibe la versión en línea, por este motivo prefiero no distribuír el documento completo con la versión del día sino compartir el método para que pueda ser creado frecuentemente.

Instalación.

Crear una carpeta en el árbol de directorios (DOCUMENT_ROOT) públicos del servidor de páginas.

Descomprimir la distribución de la herramienta en el directorio web.

Descargar la distribución actual de FuelPHP y descomprimirla en el directorio web al mismo nivel de la herramienta. 

Los archivos contenidos en la carpeta de mas alto nivel serán similares a los mostrados a continuación en la cual se utilizó la versión 1.0-RC3 del framework.

Contenidos de la carpeta web
Contenidos de la carpeta web

 

Configuración.

El único paso necesario para configurar la herramienta consiste en editar el archivo FuelPHPOneDoc/FuelPHPOneDoc.js y modificar apropiadamente el valor de la variable baseUrl la cual deberá contener la dirección absoluta en la cual se publicó localmente la documentación de FuelPHP.  De esta manera en el ejemplo anterior, si la carpeta pública web corresponde con la dirección http://localhost/onedoc/ entonces el valor de baseUrl será http://localhost/onedoc/v1.0-rc3/docs/.

Ejecución.

Acceder al URL de la herramienta utilizando un navegador web.  En el caso del ejemplo anterior sería a la dirección http://localhost/onedoc/FuelPHPOneDoc/FuelPHPOneDoc.html.

Documentación de FuelPHP en un unico documento
Documentación de FuelPHP en un unico documento

 

Requerimiento: servidor de páginas web.

Por la razón que se mencionó anteriormente, es necesario contar con un servidor de páginas web para publicar tanto el contenido de la documentación original de FuelPHP como la herramienta para modificar su presentación.

En caso de no contarse con un servidor de páginas instalado, este podrá obtenerse de diferentes maneras: Apache (todas las plataformas), Internet Information Service (sólo Windows), XAMPP (todas las plataformas) y nginx (todas las plataformas) entre muchos otros.

Si no se cuenta con ninguno de estos servidores de páginas web pero se cuenta con soporte para el lenguaje Python, es posible utilizar temporalmente el servidor web de desarrollo que incluye este lenguaje.  Para utilizarlo será necesario abrir una terminal y ubicarse en el directorio que se convertirá en público a través de web e invocar la aplicación.

$ cd /home/jimezam/tmp/FuelPHP

Si cuenta con soporte para Python 2.x:

$ python -m SimpleHTTPServer

En cambio, si se cuenta con soporte para Python 3.x, la instrucción a ejecutar será la siguiente.

$ python -m http.server 8000

En ambos casos el puerto que se utilizará para lanzar el nuevo servidor web será el 8000 así que este tendrá que ser tenido en cuenta durante la determinación del respectivo URL.  En este caso, el URL que deberá ser consultado será http://localhost:8000/FuelPHPOneDoc/FuelPHPOneDoc.html.