DEV Community

Jorge Eψ=Ĥψ
Jorge Eψ=Ĥψ

Posted on • Originally published at jorge.aguilera.soy on

Introducción a Antora

| | Creo que para aprovechar al máximo esta entrada, puede resultar de interés la serie de post sobre asciidoc(https://jorge.aguilera.soy/blog/2020/intro-asciidoctor-1.html]) |

| | Este post es una breve introducción a Antora y no sirve como guía completa. Simplemente intenta dar unavisión general de qué es, para qué sirve y las líneas generales de cómo usarlo. Para un mayor detalle recomiendola documentación del proyecto, generada con el propio Antora (https://docs.antora.org/) |

Antora

Antora es un generador de sites estáticos (static-site) destinado, principalmente, a la documentación de proyectoscon múltiples repositorios y/o versiones de desarrollo.

A diferencia, o mejor dicho, como añadido, a usar simplemente Asciidoctor en un proyecto es que mientras que esteúltimo toma los fuentes de un proyecto en un momento dado, Antora da un paso más y permite centralizar la documentaciónde múltiples repositorios así como utilizar diferentes ramas de cada uno de ellos.

Para entenderlo mejor veamos un caso de uso bastante común.

Supongamos que tenemos un producto muy molón donde participan tres equipos:

  • servicios, mantienen una aplicación REST que ofrece endpoints al core del negocio

  • admin, usando los endpoints y otras fuentes de datos mantienen un dashboard de administración

  • front, equipo que desarrolla el aplicativo que los clientes consumen en su día a día

Cada equipo trabaja en un repositorio diferente y tiene a su vez diferentes ciclos de vida (con todas sus dependenciasy problemas que esto pueda llevar) y cada uno tiene, dentro de su repositorio, su apartado de documentación. Comoson gente que se preocupa por ella usan #doc-as-code como filosofía y tanto la documentación como el código residenen el mismo repo, se revisa que cada pull request lleve su documentación actualizada, etc. e incluso despliegan a unservidor cada proyecto despues de cada despliegue.

Pero el problema es que cada site es independiente del otro siendo la única forma de tenerlos enlazados el alojarlosen el mismo servidor pero en diferentes directorios. Así mismo tienen un infierno para mantener la documentaciónde las diferentes versiones del producto.

Es en estas situaciones donde Antora puede ayudarnos a centralizar en un único sitio la documentación de todos elloscomo un único site.

Multibranch

Figure 1. https://antora.org/

Repo central

Vamos a crear un proyecto que servirá como aglutinador del resto. Por simplicidad en este repo vamos a ponerla documentación común a todos los demás, como puede ser documentación corporativo, un glosario de términos de negocio,etc

Crearemos la siguiente estructura de directorios y ficheros:

diag 00797abd87ecb9a2b8902248106df8c5

En pages va a residir nuestra documentación. Para este ejemplo va a consistir en simples páginas sin reutilizar partes,ni imágenes, etc y son documentos asciidoctor típicos, donde puedes incluir tus secciones, diagramas, etc. Así mismopuedes enlazar una página con otra pero en lugar de usar la macro link usaremos una nueva macro de Antora, xrefla cual podemos ver como una extensión a aquella y que nos servirá más adelante para enlazar con otros módulos

nav.adoc es un fichero asciidoctor destinado a customizar el menú de navegación de este módulo:

* xref:index.adoc[Home]
* xref:glossary.adoc[Glosario]
Enter fullscreen mode Exit fullscreen mode

antora.yml es el fichero que configura el módulo en cuestión. Cuando "apuntamos" al generador sobre un proyecto,este buscara de forma recursiva ficheros antora.yml y donde lo encuentre asumirá que se trata de un módulo de antora.De esta forma podemos tener múltiples módulos en un repo y en el directorio que queramos sin estar estado a unodeterminado por Antora. El contenido de este fichero es simple:

name: main
title: Welcome to XXXX
version: final
nav:
  - modules/ROOT/nav.adoc
Enter fullscreen mode Exit fullscreen mode

donde lo más destacado es el atributo name que da un nombre al módulo para ser encontrado cuando usemos xref.Versión es un identificador de texto y sirve para cualificar aún más cuando usemos xref

public.yml es el fichero de configuración principal y en donde decimos qué repositorios, ramas, diseño, etcvamos a usar para generar un site. Puede tener el nombre que quieras y puedes tener incluso varios cada uno de ellosdestinado a generar un site diferente (por ejemplo public.yml para unir un moódulo de marketing junto con unmodulo de tu API, y otro private.yml donde documentas la arquitectura interna, junto con código, etc)

site:
  title: My Site
  url: https://jorge.aguilera.soy
  start_page: main::index.adoc
content:
  sources:
    - url: ./
      start_path: docs
      branches: HEAD

    - url: https://gitlab.org/jorge-aguilera/product-api.git
      start_path: src/docs
      branches: [develop, 1.0]

ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

asciidoc:
  extensions:
    - asciidoctor-plantuml
  attributes:
    plantuml-server-url: 'http://www.plantuml.com/plantuml'
    plantuml-fetch-diagram: true

output:
  clean: true
  dir: ./build/public
  destinations:
    - provider: archive
Enter fullscreen mode Exit fullscreen mode

Básicamente le indicamos a antora qué repositorios queremos utilizar (en este ejemplo el propio repositorio másotro que se aloja en gitlab.org llamado product-api dentro del grupo jorge-aguilera). Además le indicamos de cadarepositorio qué branch queremos usar. Puedes indicar varios branch separandolos por coma.

También le indicamos qué diseño usar (ui.zip) el cual tiene que ser una url a un fichero zip (localo una URL de donde obtenerlo). Por ahora vamos a usar un bundle público por defecto de Antora alojado en gitlab.com

Mediante output configuraremos el directorio de salida (recuerda que al poder tener varios ficheros yml puedeshacer que cada uno de ellos genere en un directorio diferente)

Servicios

Por otra parte el equipo de Servicios ha creado una estructura similar en un directorio de su proyecto (por ejemplosrc/docs tal como indicamos en public.yml en el apartado anterior)

diag 854b30c22709ee167251cda2d50d7e86

Recuerda que el directorio puede estar donde te interese en este proyecto y lo único que tenemos que especificarloen el yaml que une los repositorios.

En este ejemplo hemos creado dos módulos: ROOT e internal pero sólo vamos a incluir el primero como parte de ladocumentación pública mientras que el otro lo podríamos usar en uno para cosas internas

Así mismo este proyecto tiene al menos 2 branches: develop y 1.0. Para cada una de ellas Antora generará ladocumentación que contengan de forma separada permitiendo al lector cambiar entre ambas versiones en el mismo site

Build

Para construir el site podemos instalar Antora y ejecutarla en local o bien si dispones de docker ejecutar el siguientecomando:

ANTORA_IMAGE=jagedn/antora-plantuml
docker run -u $UID --privileged -v $(pwd):/antora --rm -it $ANTORA_IMAGE --cache-dir=./.cache/antora public.yml
Enter fullscreen mode Exit fullscreen mode

ANTORA_IMAGE es una imagen que he generado usando el Dockerfile oficial pero añadiendo la extensión de diagramas (noincluida por defecto). Si quieres usar la imagen oficial simplemente cambialo por antora/antora

Como puedes ver el comando monta el directorio actual como un directorio /antora y le indica el yaml que queremosusar. Tras ejecutarse el propio docker borra el contenedor con --rm.

Así mismo como usamos repositorios externos podemos bajarlos una sola vez y mantenerlos en una cache o quitar estaopción si queremos que cada vez que ejecutemos el build se vuelva a bajar (recomendado al principio cuando estáshaciendo muchos cambios en ambos proyectos)

Si todo ha ido bien únicamente resta publicar el contenido generado mediante algún sistema tipo Apache, Nginx, GithubPages, etc copiando el directorio build/public generado por el comando.

Referencias

Algunos sites generados con Antora:

Top comments (0)