ARTIGOS

PHPDOX para gerar documentação automática em PHP

Como gerar documentação automaticamente a partir dos fontes de seu projeto

Fonte: http://phpdox.de/
Documentação: http://phpdox.de/documentation.html

O phpDox é um gerador de documentação para projetos PHP. O foco principal da ferramenta está no enriquecimento da documentação gerada, adicionando detalhes como: composição do projeto, complexidade e muito mais.

Requerimentos

A versão atual do phpDox é: 0.12 e para ela a versão necessária do PHP é 7.1 ou superior. Para usuários que usarem versões anteriores do PHP devem usar o phpDox 0.11.2. Os demais requisitos serão instalados juntamente com a ferramenta.

Instalação

Instalação via Phar

O phpDox é disponibilizado com um instalador próprio, usando um arquivo phar, para tal você pode obter uma versão desse arquivo pelo endereço de lançamentos de versões:https://github.com/theseer/phpdox/releases/latest. Você deve usar o phive para executar a instalação.

$ phive install phpdox

Agora você pode executar o phpDox pela linha de comando.

$ tools/phpdox --version

Se a instalação foi concluída com sucesso você terá o seguinte retorno:

phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors

Instalação via Composer

Para instalar usando o composer basta executar o seguinte comando:

$ composer require --dev theseer/phpdox

Agora você pode executar o phpDox pela linha de comando.

$ vendor/bin/phpdox --version

Se a instalação foi concluída com sucesso você terá o seguinte retorno:

phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors

Comandos básicos

Para obter ajuda e aprender os comandos básicos do phpDox você deve executar essa linha em seu terminal:

$ vendor/bin/phpdox --help

Retorno:

phpDox 0.12.0-dev - Copyright (C) 2010 - 2019 by Arne Blankerts and Contributors
Usage: phpdox [switches]
  -f, --file       Configuration file to use (defaults to ./phpdox.xml[.dist])
  -h, --help       Prints this usage information
  -v, --version    Prints the version and exits
  -c, --collector  Run only collector process
  -g, --generator  Run only generator process
      --backends   Show a list of available backends and exit
      --engines    Show a list of available output engines and exit
      --enrichers  Show a list of available output enrichers and exit
      --skel       Show an annotated skeleton config xml file and exit
      --strip      Strip comments from skeleton config xml when showing

Configuração do `phpDox`

Para configurar o modo de execução, diretório do projeto, extensão de saída e todas as outras configurações, você precisa criar um arquivo chamado phpdox.xml, como esse arquivo espera tags específicas de configuração o phpDox oferece um arquivo com um template completo das configurações, para gerá-lo use o seguinte comando:

$ vendor/bin/phpdox --skel > phpdox.xml

O arquivo criado terá todas as tags que podem ser usadas juntamente com algum comentário educativo. Outra opção é você usar o exemplo mínimo fornecido na documentação:

<?xml version="1.0" encoding="utf-8" ?>
<phpdox xmlns="http://xml.phpdox.net/config">
  <project name="Example" source="${basedir}/src" workdir="${basedir}/build/api/xml">
    <collector backend="parser" />
    <generator output="${basedir}/build/api">
      <build engine="html" output="html"/>
    </generator>
  </project>
</phpdox>

No arquivo de configuração mostrado acima, configuramos o seguinte:

“Example” é o nome do projeto
O projeto está em $ {basedir} / src
O workdir (onde a representação XML do código-fonte está armazenada em cache) é$ {basedir} / build / api / xml
O gerador de saída é html e colocar o resultado no diretório$ {basedir} / build / api / html

A variável $ {basedir} é resolvida para o diretório que contém o arquivo de configuração.

Anotações

O phpDox não possuí uma lista especificando quais anotações (todo, author, etc) serão analisadas. Todas as anotações presentes no projetos são interpretadas pelo phpDox. No entanto, apenas algumas são exibidas nos templates HTML, as anotações visíveis são:

Global
Class, Interface, Trait
- Nenhuma anotação específica
Propriedades, Constantes
- @var
Funções

Enriquecedores

Enriquecedores ou Enrichers são usados para que as documentações sejam geradas com ainda mas informações. O phpDox disponibiliza sete enriquecedores:

Build : Enriquecedor padrão e sempre ativo, gera dados sobre a geração da documentação (informações da plataforma, informações do phpDox)

Git : Adiciona o branch a partir da qual a documentação foi construída, também exibe o histórico do git em classes e interfaces.

Display the branch from which the documentation was build, also display git history on classes/interfaces/traits

Checkstyle e PHPCS : Em todas as classes, interfaces e traits, são exibidas listas com violações encontradas no relatório do phpcs.

PHPMessDetector : Em todas as classes, interfaces e traits, são exibidas listas com violações encontradas no relatório do phpmd.

PHPUnit Em todas as classes, será exibido um resumo com os testes bem sucedidos e os que falharam.

PHPLoc : Na página inicial, são exibas estatísticas geradas a partir do PHPLoc.

Engines

Engines são os métodos usados para analisar o projeto e transformar essas informações e documentação. O phpDox tem duas engines:

HTML
XML

Como usar

Com o arquivo phpdox.xml configurado, o desenvolvedor só precisa executar uma linha de comando para gerar a documentação de um projeto:

$ vendor/bin/phpdox -f phpdox.xml

Informações da engine usada, localização do projeto entre outros devem ser configuradas no arquivo phpdox.xml.

Você pode verificar demonstrações do uso da ferramente em: http://phpdox.de/demo/PHPUnit/index.xhtml.