La documentacion de Costasur, la estamos realizando con un Bundle de Symfony llamado Easybook.
Con este Bundle podremos generar documentos en format .pub .pdf o .html a partir de un fichero en texto plano con extensión .md.
A continuación pasaremos a describir cuales son los requisitos previos que necesitamos tener instalados en nuestro sistema para que todo funcione correctamente.
Como hemos dicho anteriormente, Easybook, es un Bundle de Symfony, por lo tanto para empezar deberemos de tener instalado el framework de Symfony (versión 2.1 en adelante).
Para realizar dicha instalación, antes tendremos que leer y aplicar el primer capítulo de la documentación principal de Costasur. En este capítulo, instalaremos el proyecto de Costasur y de esta forma tendremos Symfony instalado correctamente, ya que es el framework que usamos en el proyecto.
El Bundle Easybook, ya lo tendremos configurado correctamente gracias al paso anterior, por lo tanto solamente tendremos que verificar que esté instalado correctamente en la siguiente ruta.
.../vendor/easybook/easybook
Y por otro lado nos aseguramos que está la documentación actual.
.../src/Costasur/DocumentationBundle/Doc/
Sami es un bundle de nuestro amigo Fabien Potencier. En este articulo nos explica en que consiste y porque lo creó.
Básicamente hace lo mismo que phpdocumentor, pero de una forma mas sencilla y con menos añadidos. Recorre toda nuestra aplicaciñon para para analizarla y documentarla. Utiliza plantillas twig para presentar los resultados y finalmente nos genera una aplicación html con los resultados.
Para la instalacion solo agregamos a require de nuestro composer:
“sami/sami”: “dev-master”
Para comprobar que todo ha ido bien lo probamos desde /vendor/bin ejecutando sami.php sin argumentos.
Disponemos de un fichero de configuración que soporta incluso varias versiones, temporalmente este fichero se encuentra en:
app/config/samicfg.php
Para genera el codemap de pnuestro src nos vamos a vendor/bin y ejecutamos:
./sami.php update ../../app/config/samicfg.php
NEW: Para facilitar el uso de este bundle hemos creado un comando propio:
app/console costasur:generate:document
Este comando realiza varias operaciones, las veremos mas adelante. Nos interesa usarlo, ya que una de estas operaciones es ejecutar Sami.
Este bundle se utiliza para convertir ficheros htm en formato pdf o imagen. Para ello tira de “wkhtmltopdf”.
Se habla de él de forma detallada en el Capitulo 5 de libro "Instalacion del Entorno de Trabajo".
Una vez que ya tenemos nuestro sistema configurado correctamente, vamos a ver donde se encuentran los directorios de la documentación.
Abrimos el proyecto con nuestro IDE o editor de texto, y abrimos la siguiente ruta:
.../src/Costasur/DocumentationBundle/Doc/*
Dentro del directorio que vimos en el apartado anterior, podemos ver como las documentaciones se estructuran de la siguiente forma:
root/
Contents/
chapter1.md
chapter2.md
appendix1.md
Output/
print/
book.pdf
html/
config.yml
En el directorio Contents, están los distintos capítulos, donde cada uno de ellos están englobados en un fichero de extensión .md
En el directorio Output, están los distintos ficheros generados por Easybook, recordemos que pueden ser PDF, HTML o .Epub.
Por otro lado el config.yml es el fichero de configuración, donde podremos definir los parámetros generales de la documentación, como es el título, autor, el numero de capítulos que tiene, qué capitulos están incluidos en el libro, etc ...
Para terminar, el fichero generate.sh, es el fichero que compilamos y generamos el pdf. Una vez que tenemos el fichero abierto, con el entorno Sublime Text 2 por ejemplo, lo compilamos con el atajo de teclado ctrl + b y nos generará un PDF, en el directorio Output/print con el nombre book.
De esta forma ya sabemos donde se encuentra los distintos ficheros de la documentación y para qué sirve cada uno.
Una vez que sabemos como está estructurado Easybook, vamos a comenzar a crear un nuevo libro.
En primer lugar para crear un nuevo libro, hacemos los siguientes pasos:
cd /var/www/costasur/
vendor/easybook/ vendor/easybook/easybook/book new "Test" --dir="src/Costasur/DocumentationBundle/Doc"
/var/www/costasur/src/DocumentationBundle/Doc/Test
Una vez creado el libro, el siguiente paso es configurarlo. Para ello abrimos el fichero config.yml que está en el raiz del directorio del libro y lo más importante que tenemos que configurar son los siguientes campos.
Por defecto se nos crea dos capítulos como podemos ver a continuación:
contents: # available content types: acknowledgement, afterword, # appendix, author, chapter, conclusion, cover, # dedication, edition, epilogue, foreword, # glossary, introduction, license, lof (list of figures), # lot (list of tables), part, preface, prologue, # title, toc (table of contents) - { element: cover } - { element: toc } - { element: chapter, number: 1, content: chapter1.md } - { element: chapter, number: 2, content: chapter2.md }
Si quisiesemos crear un nuevo capítulo más , añadiriamos la siguiente línea, donde chapter3.md es el nombre del fichero que contendrá el capitulo en sí dentro del directorio del libro dentro de Contents.
- { element: chapter, number: 3, content: chapter3.md }
Una vez que tenemos el libro configurado y creado, nos faltaría empezar a crear el contenido de los capítulos. Para ello abrimos el fichero md del capitulo, para recordar, este fichero debe estar en:
/var/.../DocumentationBundle/.../*Contents*/chapter1.md
El libro se escribe en un fichero de texto plano, el cual usa la sintaxis llamada Markdown.
Referencia de sintaxis. Enlace
Es indispensable leer la documentación de Markdown. Y usar 4 espacios para indentar...
En este apartado iremos añadiendo las sintaxis más utilizadas a lo largo de la documentación.
# Documentacion --> título h1 ## Primera entrada --> subtítulo h2 ### Primera Subentrada --> h3 ...
Con markdown es muy fácil crear listas desordenadas (ul)
* Test 1 * Test 2
y ordenadas (ol)
1. Test 1 2. Test 2
Por otro lado podemos incrustar o pegar código html en nuestro libro, simplemente indentándolo. Si queremos que se resalte la sintaxis apropiada lo indicaremos entre corchetes.
Así este código:
[php]
<?php
echo "Hola mundo";
?>
Genera el contenido:
<?php echo "Hola mundo"; ?>
Entre las etiquetas que hay disponibles están [bash], [php], [apache](para configuración), [ini] y casi la que os haga falta, ya que easybook internamente usa GeSHi http://qbnz.com/highlighter/ para el resaltado.
El codigo Markdown no es muy complejo, pero aún así, hechamos en falta un buen editor visual en Linux, que nos ayude en nuestra tarea de documentar.
Para Windows existe MarkdownPad, que es aceptable.
En Linux tenemos reText, que parece bastante básico.
Para Sublime text 2, tenemos un paquete interesante:
*Markdown sublime text preview*
Nos facilita, de forma sencilla (Alt+M), una vista previa de como quedará nuestro texto. Esta vista se actualiza al salvar cambios en nuestro fichero y tan solo tendremos que resfrescar el navegador, para ver el nuevo contenido.
Para generar toda la documentación HTML-PHP hemos creado un comando de consola:
app/console costasur:generate:documentation
Este comando, sin argumentos, realiza los siguientes pasos:
Este comando encuentra dentro de DocumentationBundle "DocumentationCommand.php".
Para nas información sobre este comando ejecutenlo con el argumento --help.
Todo lo que se generase manda a la carpeta 'public' de este bundle. A su vez esta carpeta está linkeada en el directorio web de Symfony.
Para acceder a la documentación lo haremos desde
documentation.tratewolocal.com
Por ultimo y de manera temporal disponemos de este fichero:
/src/Costasur/DocumentationBundle/Resources/public/index.html
Debemos editarlo a mano, para añadir los nuevos libros que generemos.
Ni que decir tiene, la importantia de este punto, nos ayudará a comprenderlo mejor.
Seguiremos una serie de reglas y metodos para unificar criterios.
En ellas guardaremos mucha información. Debén seguir este diseño según su tipo:
/**
* ▌▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
* ▐ ᨈ
* ▐ © COSTASUR.com @version 1.0 @author Nobre y Apellidos <correo@costasur.com>
* ▌ ᨆ
* ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ */
/**
* » Clase creada generar los assets como links.
* ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
* - @see http://documentation.costa.com/codemap/Costasur/fichero.html
* - @version 1.0 @author Nobre y Apellidos <correo@costasur.com>
* └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
*/
/**
* » Función que sirve para
*
* @param Nombre $var Describe el parametro
*/
Variable:
[php] /**
Para agilizar la labor de generar las cabeceras hemos creado varios snippets.
Para que el snippet obtenga nuestros datos debemos crear este fichero y poner nuestro nombre y correo correctamente. Debemos crearnos este fichero con nuestros datos:
/home/Usuario/.config/sublime-text-2/Packages/User/Default.tmPreferences
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>name</key> <string>Globals</string> <key>scope</key> <string></string> <key>settings</key> <dict> <key>shellVariables</key> <array> <dict> <key>name</key> <string>TM_FULLNAME</string> <key>value</key> <string><![CDATA[NUESTRO NOMBRE Y APPELIDOS]]></string> </dict> <dict> <key>name</key> <string>TM_EMAIL</string> <key>value</key> <string><![CDATA[NUESTRO NOMBRE @costasur.com]]></string> </dict> </array> </dict> </dict> </plist>
Para los snippers, basta con generar estos ficheros, copiando el contenido:
/home/Usuario/.config/sublime-text-2/Packages/User/cabeceraFichero.sublime-snippet
<snippet> <content><![CDATA[ /** * ▌▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ * ▐ ᨈ * ▐ © COSTASUR.com @version 1.0 @author ${global:$TM_FULLNAME} <${global:$TM_EMAIL}> * ▌ ᨆ * ■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ */
]]>
</content>
<tabTrigger>/</tabTrigger>
<scope>source.php</scope>
</snippet>
/home/Usuario/.config/sublime-text-2/Packages/User/cabeceraClase.sublime-snippet
<snippet> <content><![CDATA[ /** * » ${1:Descripción de la Clase}. * ┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐ * - @see http://documentation.costa.com/codemap/Costasur/${2:Ruta de la documentación}. * - @version 1.0 @author ${global:$TM_FULLNAME} <${global:$TM_EMAIL}> * └─────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘ */
]]>
</content>
<tabTrigger>/</tabTrigger>
<scope>source.php</scope>
</snippet>
/home/Usuario/.config/sublime-text-2/Packages/User/cabeceraMetodo.sublime-snippet
<snippet> <content><![CDATA[ /** * » ${1:Descripción del Método}. * */ ]]> </content> <tabTrigger>/</tabTrigger> <scope>source.php</scope> </snippet>
/home/Usuario/.config/sublime-text-2/Packages/User/cabeceraVariable.sublime-snippet
<snippet> <content><![CDATA[ /** * » @var ${1:Descripción de la Variable}. */
]]>
</content>
<tabTrigger>/</tabTrigger>
<scope>source.php</scope>
</snippet>
Para usarlos basta con escribir "/" y posteriormente pulsar la tecla "Tabulador". Sublime nos mostrará una lista con los snippers disponibles para ese comando.
Debemos hacer uso de las etiquetas @, para documentar nuestro código (@param, @return, @thows ...), si bien, será el PSR el que nos marcará el contenido mínimo que deben tener nuestras cabeceras.