Gerando documentação do seu sistema utilizando a API SAMI

Fala pessoal tudo tranquilo?

Quem nunca se deparou com a necessidade de documentar o sistema que está desenvolvendo, para que outros programadores consigam realizar novas implementações, correções ou até mesmo consumir a API.

Sabemos que a documentação é algo essencial e indispensável no desenvolvimento de softwares para garantir a longevidade de nossos sistemas. O PHP não fica para trás neste quesito, atualmente no PHP-FIG está em processo de “Draft” a PSR-5 visando um padrão para PHPDoc para comunidade PHP. Este post não visa analisar nem menos discutir sobre a PSR, e sim demostrar a criação de forma simples a documentação do nosso sistema.

Mencionado isso, Show me the code!!!

Para darmos início com o exemplo, vamos construir a estrutura da nossa aplicação, tendo a seguinte estrutura:

docs
- config.php
- sami.phar
src
- App
  - Controller
    - ProductController.php
  - Model
    - Product.php
  - Service
    - ProductList.php

Lembrando que tanto a estrutura, classes e códigos são meramente ilustrativo, para servir de base para nossa documentação. Com isso peço que não se apegue a nomes e ações, pois não é este o foco do post.

Continuando com nosso exemplo, devemos acessar o repositório do projeto Sami no GitHub.

Instalação

Devemos adquirir o arquivo .phar, e para isso temos duas possibilidades, sendo:

Pela linha de comando, utilizando CURL.

1
curl -O http://get.sensiolabs.org/sami.phar

Baixando diretamente pelo link o arquivo sami.phar.

Após a realização do download, vamos implementar o conteúdo do nosso arquivo de configuração config.php, localizado dentro do diretório docs.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
<?php

use Sami\Sami;
// Componente desenvolvido pela Sensiolabs, para encontrar arquivos e diretórios http://symfony.com/doc/current/components/finder.html
use Symfony\Component\Finder\Finder; 

$iterator = Finder::create()
  ->files()
  ->name('*.php')// todos os arquivos .php
  ->in(__DIR__.'/../src'); // local onde deverá realizar a verificação.

$configuration = [
  'theme'     => 'default',
  'title'     => 'Test Sami API', // Título que será exibido na view HTML
  'build_dir' => __DIR__.'/build', 
  'cache_dir' => __DIR__.'/cache',
];

return new Sami($iterator, $configuration); // O arquivo DEVE retornar uma instancia de Sami.

Após as configurações serem realizadas, devemos acessar o diretório do nosso projeto pelo terminal.

terminal_para_rodar_comando_sami

Agora basta utilizar o seguinte comando para gerar a documentação.

1
php docs/sami.phar update docs/config.php

Após executar o comando será exibido o seguinte resultado.

geracao_da_documentacao

Vamos acessar o diretório dosc/build e abrir o arquivo index.html.

documentacao_gerada

Pronto, foi gerado a documentação do nosso sistema, de forma muito simples.

Agora cabe alguns apontamentos

Nós utilizamos o comando update e com isso ele gera automaticamente o parse e o render da nossa documentação, porem podemos fazer estes dois processo de forma isolada.

Para gerar somente o parser, devemos executar o comando parser.

1
php docs/sami.phar parser docs/config.php

E para gerar o render, devemos utilizar o comando render.

1
php docs/sami.phar render docs/config.php

Muito simples e óbvio hehehe.

O que você pode estar se perguntando é, “Mas Diego, nós geramos a documentação de uma pequenina aplicação, será que aquenta gerar a documentação de uma aplicação de grande porte?”.

Minha resposta é, SIM!!! E para lhe provar basta você acessar a documentação da API do Symfony.

Esta demonstração apenas arranhou as possibilidades de uso da ferramenta, podendo por exemplo criar layaut.

Caso tenham alguma dúvida no código podem acessar o repositório no GitHub deste post.

Espero que tenham gostado, até a próxima! 🙂

Instalação#

Instalação