Recupera la ilusión de documentar tu proyecto con "Asciidoctor para Dev(Ops) Vídeo de la charla en Panel Sistemas https://youtu.be/C2BiidiqmD4

1. ASCIIDOCTOR
PARADEV(OPS)
101 Panel Tech Days <jorge.aguilera@puravida-software.com>

2. WHOAMI?
Jorge Aguilera, @jagedn
muuuchos años (25) desarrollando …
y pocos documentando
incluso he publicado un libro en Amazon
https://jorge-aguilera.gitlab.io/tutoasciidoc/
https://www.amazon.es/dp/B07518QBR4

3. WHOAREYOU?
devs, systems, manager
word, open o ce, … notepad
java, maven, gradle
markdown, asciidoctor
https://gitlab.com/jorge-aguilera/101panels

4. So you built it. Nobody's using it. Did you forget the
docs? Aha!
1:08 AM - Aug 22, 2017
11 138 449
Kelsey Hightower
@kelseyhightower
Follow

5. MISPROBLEMASCONLA
DOCUMENTACIÓN

6. soy vago por naturaleza

7. no me pagan lo su ciente por intentar
formatear una hoja en Word

8. uso un IDE para programar
y un WYSIWYG para documentar

9. 80% esfuerzo es copy&paste y screenshot …
que se quedan obsoletos al momento

10. versionado y ver las diferencias
(las que importan, no las de formato)

11. reutiliqueeeeee ???
sólo reutilizamos el formato

12. automatizaqueeee ???

13. ASCIIDOCTORAVISTADE
PÁJARO
Asciidoc vs Asciidoctor
Markdown vs Asciidoc
Texto y nada más que texto
Un texto con múltiples formatos ( html, pdf, ebook,
docbook, slides)
Desde línea comando, embebido maven/gradle,

14. ESTRUCTURA
= Titulo : subtitulo
autor(es)
Version xx, dd.mm.yyyy
:atributo1: valor1
:atributo2: valor2
:atributo3: valor3
:toc:
:toclevels: 4
:toc-title: Contenido
:imagesdir: ./img
Las primeras lineas definen el preambulo de un documento.
Pueden ir seguidas hasta que haya una en blanco para delimitar el bloque
== Capitulo 1
aqui empieza el primer capitulo

15. EJEMPLOS
1.
2.
3.
4.
Basico
Bloques
Multimedia
Avisos

16. INCLUDE
incluir otros cheros (obvio)
organizar en carpetas, cheros un documento largo o
compartido
reutilizar fragmentos, documentar código, etc
include::{una_variable}/una/ruta/fichero.ext[calificadores]

17. BACKENDS

18. BACKENDS
HTML
Pdf
$ asciidoctor articulo.adoc
articulo.html
$ asciidoctor -b pdf articulo.adoc
$ asciidoctor-pdf articulo.adoc
articulo.pdf

19. EXTENSIONES
Asciidoctor cuenta con numerosas extensiones y si no
existe lo que quieres … pues te lo creas

20. DIAGRAMAS
Mi favorita:
= Diagramas
.Caso de uso Registro de usuario
[plantuml]
....
left to right direction
skinparam packageStyle rect
title Registro de usuario
actor Usuario as usuario
rectangle registro{
usuario --- (registro)
(registro) .> (usuario no existe) : include
(usuario existe) <. (registro) : include
}
....
Diagramas

21. FORMULASMATEMÁTICAS
stem:[sum_(i=1)^n i^3=((n(n+1))/2)^2]
=∑
i=1
n
i
3
( )
n(n + 1)
2
2

22. SCREENSHOT
Incluso puedes usar Geb y rellenar formularios
screenshot::http://myapp/dashboard[My App Dashboard]
https://github.com/asciidoctor/asciidoctorj-screenshot

23. TUMISMO
http://puravida-software.gitlab.io/asciidoctor-extensions/

24. DEV(OPS)
¿ Qué me aporta si soy un Desarrollador ?

25. TUCÓDIGOYTUDOCU
JUNTOSFOREVER
Mismo control de versiones (SVN, Git, …)
Mismo repositorio (código y documentación en un
mismo lugar)
Incluir automáticamente código en la docu
Diferentes hojas de estilo para visualizar tu código
(coderay,pingments,…)

26. MISMOEQUIPOMISMA
HERRAMIENTA
analista genera diagramas
programador documenta código
q&a documenta los test
pipelines documentan la automatización

27. PORDONDEEMPEZAR
incluir plugins en el proyecto (maven, gradle,…)
organizar documentación (directorios y apartados
separados)
establecer puentes código-documentación (utilizar
includes)
automatizar

28. MAVEN
Incluimos el plugin en nuestro pom.xml y se añade al
pipeline automáticamente
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<sourceDocumentExtensions>adoc</sourceDocumentExte
<attributes>

29. GRADLE
Incluimos las dependencias y automaticamente
tenemos una nueva task asciidoctor .
Creamos la docu en el mismo proyecto (src/docs por
defecto) versionandola junto con el código
buildscript {
repositories {
jcenter()
}
dependencies {
classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
}
}
apply plugin: 'org.asciidoctor.convert'

30. ESTABLECERPUENTES
include::{sourcedir}/la/ruta/Fichero.java[]
include::{sourcedir}/la/ruta/Fichero.java[lines=12..18]
String hola="mundo"; // < 1 >
// tag::desdeAqui[]
hola += " cruel";
// tag::desdeAqui[]

31. VISIBILIZARLADOCU
WAR, Spring Boot: Al ser contenido estático es muy
fácil incluirla en el WAR
Servidor corporativo: ftp o scp copiar a un servidor con
Apache/Nginx
Github Pages (o Gitlab, BitBucket, …)

32. CASOSDEUSO
3 ejemplos donde podemos usarlo

33. TUTORIALES
Organizar capítulos en carpetas, imágenes, diagramas,
versionado, despliegue a WebServer
TutoAsciidoc
fuente

34. BLOGESTÁTICO
Multitud de soluciones
(Hugo,Jenkill,JBake,Middleman,etc) sin bases de datos
JBake generador de blog con contenido estático
Editar html, markdown o asciidoctor
Contenido
Presentación

35. EJEMPLO:RESTEXCEL
RestExcel aplicación Grails que ofrece un Excel
mediante REST
Código disponible en carpeta restexcel
Spring Rest Docs librería Spring para que los test
http://jorge-aguilera.gitlab.io/101-panel-tech-
asciidoctor/html5/