Generando documentación técnica

En este artículo no quiero extenderme esplicando los beneficios de documentar correctamente nuestro código; a estas alturas ya todo el mundo debería ser conocedor de los beneficios que esto aporta.

De lo que se trata en este artículo es de mostrarte como podemos generar una documentación profesional en muy pocos pasos (lanzar uno, dos, tres o cuatro comandos desde la consola y listo).

Preparando el entorno

Para generar nuestra documentación vamos a usar phpdox. Una herramienta desde la línea de comandos muy sencilla de usar y de instalar.

Instalando PHPDOX

Esta herramienta se instala vía composer lanzando el siguiente comando:

composer global require theseer/phpdox

Una vez instalada deberemos crear una variable de entorno en windows que apunte a la carpeta dónde ha sido instalado phpdox, normalmente será C:\Users\[usuario_windows]\AppData\Roaming\Composer\vendor\theseer\phpdox.

Instalando PHPLOC

PHPDOX hace uso de esta otra herramienta para completar las estadísticas de nuestro proyecto. Aunque no es obligatoria su instalación, hacerlo complementará la documentación técnica y será mucho más profesional.

Los pasos para instalar PHPLOC son los siguientes:

• Nos dirigimos a la url https://phar.phpunit.de/ y descargamos la versión de phploc.phar que necesitemos según la versión de PHP que tengamos instalada (si usamos PHP > 7.2 podemos descargar las versiones de phpdox > 7, para una versión inferior a la 7 de PHP, descargaremos la versión 6 de phploc)
• Guardamos el archivo descargado en una carpeta de nuestro disco duro y creamos un archivo phpdox.bat dentro, con el siguiente contenido:

  @php "%~dp0phploc.phar" %*

• Ahora pondremos nuestra nueva carpeta dentro de las variables de entorno de windows.

Instalando PHPMD

PHPMD (PHP Mess Detector) es un proyecto maduro que proporciona un conjunto diverso de reglas predefinidas para detectar "olores" de código y posibles errores dentro del código fuente analizado.

Su instalación es a través de composer:

composer global require "phpmd/phpmd"

Una vez instalado es recomendable añadirlo a las variables de entorno de Windows (tal y como hemos hecho ya en ocasiones anteriores con otros componentes).

Instalando PHPCS

La instalación de esta herramienta ya ha sido tratada en este otro post: USAR LA GUÍA DE ESTILO DE DRUPAL CON PHPCS Y VISUAL CODE.

Si vamos a usar esta herramienta para añadir su salida a la documentación, existe un bug conocido en PHPDOX cuando se usa bajo Windows (#323).

Para solventarlo nos debemos dirigir a la carpeta de instalación de PHPDOX y modificar la función enrichUnit que encontraremos en src/generator/enricher/checkstyle/CheckStyle.php.

La nueva función quedará de la siguiente manera:

private function enrichUnit(AbstractUnitObject $ctx) {
    $file = $ctx->getSourceFile();
    $file = str_replace(array('/', '\\'), DIRECTORY_SEPARATOR, $file);
    if (isset($this->findings[$file])) {
        $this->processFindings($ctx->asDom(), $this->findings[$file]);
    }
}

Configurando PHPDOX

PHPDOX buscará en nuestro directorio de ejecución un archivo phpdox.xml que servirá para indicar los parámetros a usar, así como las herramientas auxiliares.

El contenido de este archivo, y que yo uso en mis proyectos, es el siguiente:

<?xml version="1.0" encoding="utf-8" ?>

<phpdox xmlns="http://xml.phpdox.net/config" silent="false">

  <project name="module_template" source="${basedir}" workdir="${basedir}/.tmp-doc/phpdox/xml">

    <property name="author.name" value="Óscar Novás" />
    <property name="author.mail" value="hola@oscarnovas.com" />

    <collector publiconly="false" backend="parser" encoding="auto">

      <include mask="*.php" />
      <include mask="*.module" />
      <include mask="*.install" />
      <include mask="*.inc" />

      <exclude mask="*.yml" />
      <exclude mask="*.xml" />
      <exclude mask="*.po" />
      <exclude mask="*.css" />
      <exclude mask="*.js" />
      <exclude mask="*.twig" />
      <exclude mask="*.json" />
      <exclude mask="*.md" />

      <exclude mask="**node_modules**" />
      <exclude mask="**vendor**" />

      <inheritance resolve="true">
      </inheritance>

    </collector>

    <generator output="${basedir}/documentation">

      <enrich base="${basedir}">

        <source type="phploc">
          <file name=".tmp-doc/phploc.xml" />
        </source>

        <source type="git">
          <git binary="git" />
          <history enabled="true" limit="15" />
        </source>

        <source type="phpcs">
          <file name=".tmp-doc/phpcs.xml" />
        </source>

        <source type="pmd">
          <file name=".tmp-doc/phpmd.xml" />
        </source>

      </enrich>

      <build engine="html" enabled="true" output="html">
        <template dir="${phpDox.home}/templates/html" />
        <file extension="xhtml" />
      </build>

    </generator>

  </project>

</phpdox>

Lo que hacemos con este archivo es indicar un directorio temporal (.tmp-doc) y un directorio de destino para la documentación (documentation).

Aunque estas carpetas se deberían crear automáticamente, es recomendable hacerlo manualmente para evitar sorpresas indeseadas.

También le indicamos que herramientas queremos que incluya en la documentación: el histórico de git, los errores de phpcs o la información de phploc.

Generar la documentación técnica

Para generar la documentación técnica son necesarios cuatro comandos (si deseas incluir la información de phpcs, phpmd y phploc).

Si tienes XDEBUG habilitado en tu php.ini deberás desactivarlo para que los comandos no te lancen un error.

Lo primero que haremos será generar la información de phploc:

phploc.bat . --log-xml=.tmp-doc/phploc.xml

Este comando genera un archivo xml dentro de nuestra carpeta temporal (tal y como definimos en el archivo phpdox.xml). Si queremos evitar el tener que poner la extensión .bat (o el comando entero) desde git-bash os pongo lo que tenemos que hacer en el siguiente apartado.

Si quieres incluir también la información de PHPMD deberás ejecutar el comando:

phpmd . xml phpmd.xml --report-file=.tmp-doc/phpmd.xml

Ahora es el momento de generar el archivo que contendrá todos los errores de codificación (aquellos que no cumplen la hoja de estilo de Drupal):

phpcs --report=xml --report-file=.tmp-doc/phpcs.xml

Con estos dos archivos ya generados, pasaremos a generar la documentación. El comando para ello es muy sencillo:

phpdox

Pues listo, ya tienes tu documentación generada dentro de la carpeta documentation/html.

Crear un alias para los comandos en git-bash

Si usamos la línea de comandos proporcionada por git, podemos crear un alias para nuestro comando y simplificar la escritura del mismo.

Para esto generaremos un archivo llamado .bashrc en nuestra carpeta de usuario de windows (C:\Users\[usuario_windows]\.bashrc).

Ahí incluiremos lo siguiente:

# ------------------------------------------------------------------------------
# Custom alias
# ------------------------------------------------------------------------------

alias run_phploc='phploc.bat . --log-xml=.tmp-doc/phploc.xml'
alias run_phpcs='phpcs --report=xml --report-file=.tmp-doc/phpcs.xml'
alias run_phpmd='phpmd . xml phpmd.xml --report-file=.tmp-doc/phpmd.xml'
alias run_phpdox='run_phploc && run_phpcs && run_phpmd && phpdox'

Es posible que tengamos que abrir un par de veces nuestro terminal para que se configuren correctamente estos alias. Puedes lanzar el comando alias para comprobar que se han configurado correctamente.

Ahora bastará con lanzar el comando run_phpdox para ejecutar todos los comandos con sus parámetros y no tener que recordarlos, evitando así posibles errores y teniendo sólo que recordar un único comando.

No quiero ser pesado con el tema pero, recuerda, si tienes XDEBUG habilitado en tu php.ini deberás desactivarlo para que los comandos no te lancen un error.

Personalizando la plantilla de la documentación

En ocasiones necesitaremos realizar algunos cambios para adaptar esta documentación a "nuestra marca". Para ello, deberás dirigirte a la carpeta dónde se encuentra phpdox instalado (recuerda que lo instalamos vía composer).

La ruta en cuestión es C:\Users\[usuario_windows]\AppData\Roaming\Composer\vendor\theseer\phpdox\templates\html. Aquí podrás modificar los archivos para añadir, modificar o eliminar elementos.

En mi caso, lo único que he hecho es traducir todas las cadenas al español.

Si quieres mantener la plantilla por defecto, puedes realizar una copia de este directorio, ponerle el nombre que tu quieras (ej. html_es) y sustituir en el phpdox.xml la plantilla por la que tu vas a utilizar.

Descarga de archivos

Como siempre, te recuerdo que estos archivos de configuración pueden ser descargados desde el repositorio de GitHub VSCode-settings (el cual actualizo regularmente con las nuevas configuraciones que voy descubriendo y usando).