Introducción

Esquema general de la interacción entre sistemas

Requerimientos

• MarkDown

• Git

• MkDocs

Markdown

La documentación utiliza el lenguaje de marcado Markdown

¿Qué es Markdown?

Markdown es un lenguaje de marcado que facilita la aplicación de formato a un texto empleando una serie de caracteres de una forma especial. En principio, fue pensado para elaborar textos cuyo destino iba a ser la web con más rapidez y sencillez que si estuviésemos empleando directamente HTML. Y si bien ese suele ser el mejor uso que podemos darle, también podemos emplearlo para cualquier tipo de texto, independientemente de cual vaya a ser su destino.

Referencias:

En este sitio

• Conceptos básicos de Markdown

En la web

• Markdown en español
• Sintaxis de Markdown
• Cheat Sheet

GitLab

GitLab¹ es una suite completa que permite gestionar, administrar, crear y conectar los repositorios con diferentes aplicaciones y hacer todo tipo de integraciones con ellas, ofreciendo un ambiente y una plataforma en cual se puede realizar las varias etapas de su SDLC/ADLC y DevOps.

Todo esta documentación esta contenida en un repositorio git gestionado a través de la plataforma GitLab instalado en un servidor local del Departamento de Supercómputo.

Obtención de un cuenta

Para obtener una solo basta con registrarse el GitLab del Departamento de Supercómputo https://saka.super.unam.mx/gitlab/

Acceso al repositorio GridUNAM

Una vez se tenga acceso servidor de GitLab, se debe solicitar acceso al grupo GridUNAM a Eduardo Ortega o Leobardo Itehua

Git con uso de llaves SSH

GitLab soporta dos protocolos, SSH y HTTPS, el primero te permite agregar llaves SSH y GPG.

• Para agregar una llave SSH, selecciona Setting en el ícono del avatar de tu cuenta
  
• Luego selecciona la opción SSH Keys en el frame o menú izquierdo
  
• Finalmente copiar y agregar la llave SSH del host al que se quiera dar acceso
  

MkDocs y Read the Docs

MkDocs² es un generador de sitios estáticos rápido , simple y francamente magnífico que está orientado a la creación de documentación de proyectos. Los archivos de origen de la documentación se escriben en Markdown y se configuran con un solo archivo de configuración YAML

Read the Docs³ es una plataforma de alojamiento de documentación de software gratuito de código abierto. Genera documentación escrita con el generador de documentación Sphinx o MkDocs^*.

Visualización con MkDocs

Si bien GitLab soporta la visualición de texto en formato Markdown, no cuenta con una integración de toda la documentación como lo hace MkDocs y Read the Docs, por lo si queremos verificar el resultado final del formato de la documentación en el repositorio git, tendremos que levantar un repositorio propio o local de MkDocs (Visualizaicón al vuelo) o subir nuestro cambios al repositorio git (push) para que los resultados se vean en servidor MkDocs remoto.

Local

1. Clonar el repositori git GridUNAM:
   

   git clone git@saka.super.unam.mx:gridunam/htcondor.git mkdocs-gridunam
   

2. Crear el entorno de conda:
   

   conda env create -f mkdocs-gridunam/mkdocs/server-local/mkdocs-gridunam.yml
   

3. Activar el ambiente conda:
   

   conda activate mkdocs-gridunam
   

4. Ejecutar el servidor local MkDocs:
   

   cd  mkdocs-gridunam/mkdocs
   mkdocs serve -a 127.0.0.1:8000
   

Remoto

Ejercicio

A) Clonar el repositorio

git clone git@saka.super.unam.mx:gridunam/htcondor.git mkdocs-gridunam

B) Crear el entorno de Conda

1. Crear el entorno de conda:
   

   conda env create -f mkdocs-gridunam/mkdocs/server-local/mkdocs-gridunam.yml
   

2. Activar el ambiente conda:
   

   conda activate mkdocs-gridunam
   

3. Ejecutar el servidor local MkDocs:
   

   cd  mkdocs-gridunam/mkdocs
   mkdocs serve -a 127.0.0.1:8000
   

C) Subir los cambios al repositorio a GitLab

1. Preparar los cambios
   

   git add $File
   

2. Hacer commit de los cambios
   

   git commit -m "Comentario" $File
   

3. Subir los cambios
   

   git push