7. Generación estática de sitios web#

En este tema aprenderemos a:

  1. Entender qué son los generadores de sitios web estáticos

  2. Usar sphinx con un ejemplo de SSG para documentación técnica

  3. Desplegar servicios web estáticos usando GitHub Pages (o gitlab)

Esfuerzo Necesario

El curso está organizado en 8 sesiones de clase. Cada clase (sesión) implica una dedicación de entre 2 y 4 horas.

La dedicación depende del conocimiento previo, motivación y capacidad de aprendizaje del estudiante para esa sesión en concreto.

7.1. Static Site Generators#

  1. Static Site Generators es un concepto diferente de los CMS:

    1. Generan Sitios estáticos usando HTML, CSS y JS pero …

    2. … usan un marcado ligero de texto apoyado en una estructura previa.

    3. Es decir, se construyen previamente. No hay construcción dinámica «instantánea»

  2. Arquitectura de un SSG

    1. Usan un lenguaje de marcado ligero de texto: Markdown / reStructured Text (o plantillas más o menos evolucionadas)

    2. Se genera el HTML (o PDF o ePub o …) con una Plantilla Generadora

    3. Usa un motor de renderizado HTML que genera el sitio web (estructura y archivos)

    4. El hosting es muy sencillo porque es un sitio web estático y permite un despliegue sencillo con redes de contenidos distribuidas ( CDN )

    5. Hay una versión evolucionada ( Arquitectura JAMStack ) que es un concepto más amplio (lo veremos en un tema posterior)

  3. Hay muchos ( pero muchos ) SSG

    1. Puros: tienes que reconstruir el sitio web cuando lo quieres actualizar

    2. Híbridos: partes del sitio web se actualizan de forma asíncrona (y desde un servidor) -> Arquitectura JAMStack

  4. Según la necesidad, son una opción interesante para el despliegue de sitios web:

    1. Sitios personales, profesionales, blogs, documentación, etc

    2. Ventajas:

      1. Rendimiento

      2. Seguridad

      3. SEO

    3. Inconvenientes: para sitios web complejos con alto componente de interactividad (o capa de programación muy específica)

T07-A01. Investigación sobre Sistema SSG

  1. ¿Cuantos sistemas SSG hay?

  2. ¿En qué lenguaje está escrito Jekyll?

  3. ¿Cual es su página web oficial?

  4. ¿En qué lenguaje está escrito Javascript?

  5. ¿Cual es su página web oficial?

  6. ¿En qué lenguaje está escrito Sphinx?

  7. ¿Cual es su página web oficial?

  8. ¿En qué lenguaje está escrito Hugo?

  9. ¿Cual es su página web oficial?

  10. ¿Podría desplegar mi web con Sphinx usando el servicio netlify.com?

7.2. Uso de Sphinx para generar un sitio web#

  1. ¿Porqué Sphinx?

    1. Muy orientado a documentación técnica y de código

    2. Estructura jerárquica, con índices y referencias cruzadas muy sencillas de hacer.

    3. Con uso de directivas y roles para descripción semántica de contenidos

    4. Con estilos organizados en temas y fáciles de intercambiar

    5. Muy Personalizable

  2. Arquitectura del sistema:

    1. El archivo .rst

      1. Uso de reStructured Text como lenguaje de marcado ligero

      2. Incluye marcado de texto (reST o Markdown vía un analizador )

      3. y comandos propios (directivas, roles, etc)

    2. Los directorios

      1. Archivos organizados en directorios. Desde el directorio raíz (source/).

      2. Diferencia entre código fuente (source) y el generado (build) para publicar

      3. Archivo de configuración (source/conf.py)

    3. El estilo:

      1. La ventaja es concentrarse en el contenido, no en el marcado html (usa un marcado ligero del texto)

      2. El estilo vendrá dado por un tema genérico (que puede personalizarse con ciertos conocimientos)

      3. Es muy sencillo cambiar el tema, sin tocar el contenido (cambiando la configuración).

  3. Usando Sphinx -> Generar un proyecto base:

    1. Debes decir donde va:

      1. el directorio fuente (source). Sobre el que trabajas (y compilas)

      2. el generado (build). El que publicas

    2. Defines algunas variables generales que se pueden usar a lo largo del proyecto (Nombre, autor, lenguaje, etc)

    3. Revisas los directorios que te habrá creado ( Getting Started ):

      1. tu código fuente (source) y el código generado (build)

      2. el indice principal del sitio web (source/index.rst)

      3. el archivo de configuración (source/conf.py)

    4. Con esa «plantilla» generas tu sitio web ejecutando make html (se podría generar, con la misma estructura salida en otros formatos)

    5. Abres tu navegador y cargas el archivo index.html (en el directorio compilación)

T07-A02. Crear un proyecto base con Sphinx

Instalar Sphinx en tu entorno de desarrollo.

En windows debes tener Python instalado y luego usas el instalador de paquetes PIP.

El objetivo es poder ejecutar los siguientes comandos para tener tu proyecto base y comenzar a trabajar:

> sphinx-build --version # Dice la versión del generador
> sphinx-quickstart docs

7.3. Escribir web con reStructured Text#

  1. reStructured Text Primer

    1. Todo es un párrafo (y mucho ojo a las indentaciones)

    2. Marcado en línea: negritas, énfasis y citas

    3. Encabezados. Se hace con líneas de texto (inferior o superior)

    4. Listas numeradas, no numeradas y definiciones

    5. Enlaces:

      1. Internos

      2. Externos

  2. Estructura de la página:

    1. Está estructurado en secciones (con encabezados) compuestas por …

    2. … párrafos de texto …

    3. … con algunas palabras con marcas …

    4. … y enlaces, internos o externos (inline markup)

  3. Un tutorial muy sencillo de Python Ecuador o en Piptocode

T07-A03. Aprendiendo la sintaxis reST

Puede jugar con el editor online de reST o ya trabajar directamente con tu sitio web de ejemplo, previamente generado (en index.rst, pero sin tocar la estructura generada).

Creas un archivo (.rst) que tenga:

  1. Al menos 5 párrafos, organizados en …

  2. al menos 3 secciones donde …

  3. haya texto resaltado con negrita y algún texto …

  4. organizado en una lista numerada …

  5. y varios enlaces (URL) …

Y lo generas para ver el resultado (en sphinx, al no estar incluido en el index.rst te dará un aviso)

7.4. Directivas y Roles#

  1. Puedes definir con directivas un marcado especial de un bloque (y que se comportará de una manera programada previamente). Algunos ejemplos:

    1. Para insertar una imagen .. image

    2. Para insertar avisos especiales en el texto .. note (hay varias similares)

    3. Las directivas (.. nombre-directiva::) se definen:

      1. empezando con punto punto

      2. seguidos del nombre de la directiva y dos puntos

      3. A veces seguido de un título a continuación

      4. A veces con una opción por línea (:nombre: valor), con nombre y valor

      5. y luego el bloque de texto (correctamente indentado) sobre el que se define el comportamiento

  2. Uso de roles:

    1. Puedes definir con roles un marcado especial en línea

      :rolename:`content`

    2. Hay diferentes roles (el nombre de rolename cambia) y modifica el comportamiento con el contenido

      :doc:`Contenido <content>`
     -> Incluye un enlace con título Contenido que apunta al
     documento content que está en el mismo directorio

    3. Hay muchos roles y, sobre todo, se puede seguir personalizando

      :proyectos-github:`sphinx`
     -> Podría definir que al poner ese rol me crea un enlace
     a https://github.com/sphinx.

   Es decir, que si fuese :proyectos-github:`otro`, el enlace
   sería https://github.com/otro . El rol, define el
   comportamiento de la publicación (en este caso crear un enlace)

T07-A04. Añadiendo directivas y roles

Añade al archivo de la sesión anterior:

  1. Una imagen (en URL)

  2. Y un par de bloques resaltados de forma especial (note y warning por ejemplo)

  3. Y puedes jugar a añadir una directiva o rol nuevo que no hayas visto aquí (hay muchos).

Con lo visto hasta ahora, podrías analizar archivos reST ( Ver Ejemplos ):

  1. Ejemplo 1

  2. Ejemplo 2

  3. Ejemplo 3

7.5. Organizar un sitio web con Sphinx#

  1. Sphinx está pensado para documentación ( Narrative Documentation ) y tiene un fuerte soporte para …

  2. … gestionar una estructura jerárquica de cierta complejidad.

  3. Estructura tu sitio web (con múltiples páginas)

    1. Todos los documentos han de estar referenciados (enlazados) con index.rst (documento raíz)

    2. Se usa la directiva .. toctree:: (Table Of Contents) para incluir la estructura en un documento (como un índice de contenidos)

    3. Una buena explicación (hasta minuto 9:28) aunque centrada en documentar código:

  4. Añadir referencias cruzadas:

    1. Añade un enlace a un documento en otro (pero actualiza el título del enlace automáticamente). Lo hace con el rol :doc:

    2. Añade un enlace a una sección de otro documento. Lo hace con el rol :ref:

    3. Se puede añadir un texto específico en un enlace. Por ejemplo

      :ref:`referencia al encabezado ejemplo <ejemplo>`
:doc:`documento ejemplo1 en el directorio dir1 </dir1/ejemplo1>`

  5. Añadir referencias a documentos para descargar (por ejemplo pdfs):

    1. Lo hace con el rol :download: . Puedes modificar el título del enlace (si te interesa)

    2. Gestiona posibles duplicados y coloca todos los archivos descargables en un lugar concreto

    3. La referencia al archivo es relativo (donde se llama) o (mejor) absoluto a / (archivo fuente de referencia)

T07-A05. Añade archivos (y estructura) a tu sitio web

Siguiendo con tu proyecto base generado:

  1. Añade tres archivos: archivo1.rst, archivo2.rst y archivo3.rst

  2. Cada archivo que tenga al menos dos secciones, con dos subsecciones

  3. Organízalos en dos directorios. archivo1 y archivo2 en dir1 y archivo3 en dir3

  4. Incluye los archivos en index.rst, tanto en el toctree como enlaces a los archivos (a la estructura)

  5. Añade dos archivos descargables, en el archivo 3

  6. Supón que le llamas A1_S2 a una referencia a la sección 2 del archivo 1, ¿lo podrías enlazar en el archivo1, pero en otra posición?

  7. Utilizando el mismo criterio, añade una referencia en archivo 3 a esa referencia A1_S2

7.6. Uso de Temas y Estilos con Sphinx#

  1. Sphinx usa temas (para HTML) que permiten modificar el estilo del contenido

  2. Hay algunos ya incluidos y otros que se pueden añadir (Ver Sphinx Themes Gallery )

  3. Incluir un tema a nuestro proyecto base ( HTML Theming ) implica:

    1. Modificar el archivo de configuración (/source/conf.py)

    2. … y usar diferentes variables (para configurar la salida HTML )

  4. Para escoger uno de los temas disponibles (Ver Sphinx Themes Gallery ):

    1. Dependerá de tu público objetivo

    2. No todos tienen un diseño adaptable (Responsive)

    3. Algunos ejemplos interesantes: alabaster (predeterminado), furo y Read The Docs

    4. Algunos temas están disponibles con la instalación base y otros hay que instalarlos

  5. Añadir estilos (a partir de minuto 9:28 hasta el minuto 12).

T07-A06. Añade estilo a tu proyecto base

Revisa el resultado de tu sitio web usando los siguientes temas:

  1. nature

  2. furo

  3. read the docs

7.7. Hosting web estático con control de versiones#

  1. El objetivo final del desarrollo web es:

    1. Generar html (HTML Rendering) de diferentes formas:

      1. Static Site Rendering (SSR) ->

      2. Server Side Rendering (SSR) ->

      3. Client Side Rendering (CSR) ->

      4. Static Site Generator (SSG) ->

      5. Arquitectura Híbrida (JAMStack)

    2. Tenerlo disponible en un url público (hosting)

  2. En general tienes dos opciones de hosting web (con un sistema de control de versiones):

    1. Sincronizar el directorio/s del html generado. Da igual el SSG que uses (pero en el repositorio no estaría el código fuente)

    2. Sincronizar el código fuente y desplegar de forma continua (CI). Necesitas añadir alguna integración para el SSG que uses.

  3. En concreto para subir tu sitio web y hacer hosting podrías usar:

    1. GitHub Pages - GHP:

      1. Preparas el alojamiento ( hosting ):

        1. Creas un repositorio para tu proyecto

        2. Lo configuras como GHP (Configuración -> Pages)

          1. source: el origen del sitio web

          2. branch: la rama en la que está el sitio web

      2. Subes tus recursos web o (mejor) sincronizas tu repositorio git local con github

      3. Desarrollas tu web normalmente (edit -> add -> commit) y …

      4. … se publica automáticamente en tu servidor web (username.github.io)

      5. Puedes tener de referencia la guía oficial GHP

    2. GitLab Pages - GLP ( How to … )

      1. Sirve para diferentes SSG (no tiene uno propio)

      2. Creas un repositorio para tu proyecto

      3. Configuras el mecanismo de despliegue (GitLab CI Configuration): «.gitlab-ci.yml» (decirle que copie tu sitio web a al diretorio que usa el servidor web)

      4. Y ya tienes tu sitio web publicado ( gitlab.github.io)

T07-A07. Usando hosting web con sistemas de control de versiones

Publica un sitio web usando GHP (o GLP) como hosting. Algunas consideraciones:

  1. Tu sitio web lo desarrollas en local (no usando el editor online ni subiendo archivos). Así desarrollas en local y sincronizas al repositorio remoto

  2. Modificas tu código para que la estructura funcione con urls relativos (que todos tus recursos estén bien enlazados)

  3. Envías un url público con tu sitio web (o haces un test de validación html/css)

Para entender mejor el proceso puedes hacerlo con dos sitios web (tendrás un servidor con dos directorios de dos sitios web estáticos diferentes)

7.8. Hosting web y código fuente SSG#

  1. En un sistema SSG, al ser código generado, se pueden usar sistemas de despliegue continuo (CI/CD):

    1. Desarrollas en Local: edición -> generación - publicación localhost

    2. Publicas en remoto (en url público). Subes tu sitio web de desarrollo y se publica automáticamente

    3. Y además, podrías trabajar de forma colaborativa

  2. Es imprescindible usar algún tipo de integración (Action) para generar el código salvo que publiques el HTML directamente

    1. Creas un repositorio con el código fuente de tu proyecto …

    2. … configuras algún tipo de integración para generar el código html (Con GHP podrías usar Jekyll sin ninguna integración)

    3. … configuras cuando se genera el código (cada vez que modificas un archivo o en algún momento concreto)

  3. En el caso concreto de usar Sphinx ( Deploying Sphinx … ):

    1. Preparas tu entorno de desarrollo:

      1. O creas tu proyecto en Github

      2. o sincronizas el directorio fuente (source) del que ya tienes (Ojo, no sincronices el código generado, que ya lo hará la integración)

      3. Trabajas en local para tu sitio web de prueba

      4. -> esto te permite tener tu código fuente supervisado con git (en local y en GitHub)

    2. Crea una integración específica (automatización de procesos):

      1. Con GHP: Configuras GitHub Action (hay diferentes alternativas)

      2. Con GLP: configuras Gitlab CI (hay diferentes alternativas)

    3. Ejecutas la integración y revisas el resultado (publicación)

  4. Resumen final del tema:

    1. A Static vs Dynamic Website

    2. Modern Static Site Generators

    3. Build any SSG site with GitLab Pages

T07-A08. Usando hosting web con sistemas de control de versiones

Publica tu proyecto sphinx base en GHP (o GLP):

  1. Publicas sólo el directorio html (obligatorio)

  2. Publicas sólo el código fuente y lo genera automáticamente (opcional, pero lo ideal)