Saltar la navegación

2.3.- Configuración de phpDocumentor.

Una vez hemos instalado phpDocumentor se puede trabajar con él de dos modos para generar automáticamente la documentación de nuestros proyectos PHP; se puede trabajar desde línea de comandos, mediante:

# phpdoc -o [formato_de_la_documentacion_generada] -d [carpeta_donde_estan_los_proyectos_php] -t [carpeta_donde_se_almacenan_los_archivos_de_documentacion]

por ejemplo:

# phpdoc -o HTML:frames:phpedit -d /var/www/html/ -t /var/www/html/docs/

en este caso estamos indicando que se genere la documentación en formato HTML (también es posible en formato PDF, CHM) de los proyectos de la carpeta /var/www/html/ y se almacene dicha documentación en la carpeta /var/www/html/docs/; aunque existen un gran número de parámetros para adaptar el formato de la documentación que phpdoc genere al formato que más nos interese, para ello podemos obtener información ejecutando:

# phpdoc -h

Por otra parte también es posible trabajar desde el entorno web que phpDocumentor ofrece; para lo que es recomendable establecer la configuración necesaria de donde phpDocumentor debe recoger los proyectos y a donde enviar la documentación generada; para ello podemos establecer la configuración del siguiente modo:

  • Pantallazo de configuración phpDocumentor.
    Elaboración propia (CC0)

    En la ruta donde hemos instalado phpDocumentor accedemos a la ruta: PhpDocumentor/user y duplicamos el archivo default.ini poniéndole un nombre distinto; por ejemplo: "mi_proyecto.ini".

  • Editamos el archivo que acabamos de crear y modificamos lo siguiente:

    • Para establecer la ruta donde guardar la documentación generada cambiamos la línea con el contenido: target = /you-MUST/change-me/to-fit/your-environment estableciendo la ruta que nos interese, por ejemplo: target = /var/www/html/Documentacion_de_mi_proyecto.
    • Para establecer la ruta donde se encuentran los archivos del proyecto cambiamos la línea con el contenido: directory = /you-MUST/also-change-me/to-fit/your-environment estableciendo la ruta que nos interese, por ejemplo: directory = /var/www/html/proyectos y guardamos los cambios realizados.
  • Ya para crear la documentación de nuestros proyectos entraremos en la aplicación de PhpDocumentor desde el navegador tecleando http://localhost/PhpDocumentor/ y en el Menú elegimos la opción Config, a continuación, en la lista debemos elegir la configuración y seleccionar "mi_proyecto.ini", para luego presionar Go, en esos momentos comenzará a crearse la documentación en el directorio elegido.

Para acceder a la documentación generada deberíamos seleccionar el documento "index.html" de la carpeta donde se almacenan los documentos generados y veríamos la página principal de la documentación.

phpDocumentor puede crear su propia documentación. Los ficheros fuente de esta documentación están en una subcarpeta "tutorials". Sin embargo, se debe especificar el directorio raíz de phpDocumentor como directorio de entrada a phpdoc para que se compilen estos tutoriales (phpDocumentor no procesa documentación en "tutorials" que no esté vinculada a algún código fuente, es decir, no es posible compilar sólo tutoriales). En este caso como proyecto se debe especificar "phpDocumentor" .

Para saber más

Esta web sirve como manual de referencia, guía de usuario, tutoriales prácticos, etc. sobre phpDocumentor.

Documentación phpDocumentor.