One Step Beyond

Jorge Aguilera

$whoami

$whoami

Jorge Aguilera, +25 años dándole a la tecla

$who are you

  • desarrollador …​ o no
  • asciidoctor …​ o no
  • markdown …​ deberías hacertelo mirar
  • jbake …​ sube aquí y echame una mano

Objetivo

LLevar la documentación de tu proyecto un paso más allá que el simple README.md

  • MarkDown
  • Asciidoctor
  • JBake

From

To

Step by step

Usare un proyecto alojado en Gitlab con varias ramas "incrementales" que nos irán mostrando los avances en nuestra documentación.

Si todo va bien incluso iremos viendo en vivo cómo avanza.!!

git clone git@gitlab.com:jorge-aguilera/one-step-beyond.git

Inicio del proyecto

git checkout 1-readme
  • Tenemos una idea y creamos un proyecto
  • Creamos un README donde explicamos en qué va a consistir

Comenzamos la aplicación

git checkout 2-app
  • Añadimos funcionalidades iniciales, controllers, test, …​
  • El proyecto empieza a tomar forma …​
  • y hay que contarlo al mundo así que editamos README

Saltando al ruedo

git checkout 3-pages
  • Nuestro proyecto avanza y queremos contarselo al mundo
  • Pero quien c****es se lee un README, eso es de frikis
  • Piensas en contratar un WPress, montarte un Apache …​.
  • o usar gh_pages (Github), pages (Gitlab), …​ en el mismo proyecto
  • nosotros vamos a usar Gitlab

Saltando al ruedo 1

git checkout 3-pages

Como eres hábil 1/3, usarás Asciidoctor

src/main/asciidoc/index.adoc
blabalblaba

Saltando al ruedo 2

git checkout 3-pages

Como eres hábil 2/3, usarás su imagen Docker

builddocu.sh
docker run --rm -v "$PWD":/documents/ asciidoctor/docker-asciidoctor asciidoctor -D build/docu src/main/asciidoc/index.adoc

Saltando al ruedo 3

git checkout 3-pages

Como eres hábil 3/3, lo incluirás en un pipeline de Gitlab

gitlab-ci.yml
build:
  stage: build
  script:
  - chmod +x builddocu.sh
  - ./builddocu.sh
  artifacts:
    paths:
    -  build/docu

y cada vez que hagas un commit al repo tu documentación será publicada

Saltando al ruedo 4

git checkout 4.1-asciidoc

Nuestra aplicación crece, ya tenemos más letras de canciones, funcionalidades nuevas, otras que queremos implementar, …​.

y nuestra documentación crece también …​ pero un poco "plana", no ?

Dando el salto

git checkout 5.0-jbake

Nos decidimos dar un paso adelante en la manera que tenemos de explicar nuestro proyecto y creamos un site jBake.

jBake cuenta con un plugin Gradle que se integra en nuestro proyecto sin problemas

Dando el salto

buildscript {
    dependencies {
    ...
        classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.3'
    ...
    }
}

plugins {
    ...
    id 'org.jbake.site' version '1.0.0'
    ...
}

jbake{
    ...
}

Nuestro docu-blog

git checkout 5.1-jbake

Borramos los ejemplos de jBake y empezamos a crear nuestros post

  • usaremos la carpeta blog creando una estructura de subdirectorios libre que nos ayude a organizarlos (fecha, tema, etc)
  • podremos personalizar las plantillas de la carpeta templates por ejemplo para incluir un icono propio, personalizar el menú, incluir scripts de analítica de Google, etc
  • podremos incluir nuestro propio contenido en la carpeta assets como imágenes , hojas de estilo propias, etc

Be social, my friend

git checkout 6.0-be-social

Esta rama es un ejemplo de cómo podemos incluir contenido extra a nuestro blog, por ejemplo haciendolo más social al incluir un timeline de twitter o añadiendo nuevos elementos en el menú principal para compartir la página.

Mix de contenidos

git checkout 7-slides

En esta rama simplemente es un ejemplo de cómo mezclar contenido generado por jBake con el generado por alguna otra parte de nuestro proyecto, como por ejemplo un generador de presentaciones.

De esta forma nuestro site dispondrá:

  • documentación técnica típica de Asciidoctor
  • un sistema de blog donde poder compartir artículos, comentarios, etc
  • herramientas de redes sociales
  • presentaciones
  • pdfs
  • …​

Sería fácil integrarlo por ejemplo con Disqus y poder tener feedback de nuestros usuarios (tal vez git checkout 8-disqus ? )

/