Como vimos en éste articulo dónde explico la instalación y uso de phpDocumentor en Windows a través de un archivo .phar, ahora, en esta segunda parte, vamos a crear un archivo de configuración para que nos resulte más fácil generar documentación para nuestros proyectos sin necesidad de escribir cada opción en la línea de comandos o consola.
¡Vamos allá!
El archivo de configuración de phpDocumentor, se ha de llamar phpdoc.xml y nos permite especificar todas las opciones y configuraciones necesarias que phpDocumentor necesita para generar la documentación para nuestro proyecto.
Paso 1: Crear archivo phpdoc.xml
Crea un archivo llamado phpdoc.xml en la raíz de tu proyecto (donde tengas el archivo phpDocumentor.phar) y añade la siguiente configuración básica:
<?xml version="1.0" encoding="UTF-8" ?>
<phpdocumentor configVersion="3.0">
<paths>
<output>docs</output>
</paths>
<version number="1.0.0">
<api format="php">
<source dsn=".">
<path>src</path>
</source>
<ignore>
<path>vendor/*</path>
</ignore>
</api>
</version>
</phpdocumentor>
Un poco de explicación sobre las etiquetas de configuración:
- configVersion=″3.0″: Especifica la versión del esquema de configuración que se está utilizando.
- <paths>: Relacionada con la salida de la documentación.
- <output>docs</output>: Directorio donde se generará la documentación. En el ejemplo en la carpeta docs.
- <version number=″1.0″>: Define la versión del proyecto que se está documentando.
- format=″php″: Especifica que el formato del código fuente es PHP.
- <source dsn=″.″>: Define la fuente del código que se va a documentar.
- dsn=″.″: Especifica el Data Source Name (DSN), que en este caso se refiere al directorio base desde el cual se buscará el código fuente. Al poner (.), nos referimos al directorio actual.
- <path>src</path>: Especifica el subdirectorio dentro del directorio base que contiene el código fuente a documentar. En este caso, es src.
- <ignore>: mDefine los archivos y directorios que deben ser ignorados durante la generación de la documentación.
- <path>vendor/*</path>: Especifica que todos los archivos y subdirectorios dentro del directorio vendor deben ser ignorados.
Una vez hemos creado y guardado nuestro archivo de configuración, vamos a ejecutar phpDocumentor para que genere la documentación.
Basta con escribir en la consola/terminal:
php phpDocumentor.phar
phpDocumentor leerá las configuraciones del archivo phpdoc.xml y generará la documentación en el directorio especificado.
¡Y eso es todo… por ahora! 😉
Como hemos visto, crear un archivo de configuración para phpDocumentor nos facilita la generación de documentación y nos permite mantener una documentación organizada y consistente.
El ejemplo que hemos visto es un ejemplo muy básico, pero puedes ampliarlo según tus necesidades ya que phpDocumentor ofrece muchas más opciones de configuración.
Sobre el autor
