Nuevo flujo de despliegue: setup_env.py, uv y scripts multiplataforma

Al sistema de publicación de apuntes y recursos se le han aplicado tres novedades: un script de configuración inicial del entorno, migración a uv para gestionar dependencias Python y scripts de despliegue en Python que funcionan en cualquier plataforma sin necesitar bash ni rsync.

Configuración anterior

Hasta ahora preparar el entorno de desarrollo requería ejecutar una serie de comandos git y pip a mano. En Windows había un problema adicional: los scripts de despliegue (deploy.sh, deploy-github.sh) necesitan bash y rsync, herramientas que no vienen de serie.

La solución ha sido crear un script de configuración automática y versiones Python de los scripts de despliegue.

1) setup_env.py: configuración del entorno en un solo paso

setup_env.py automatiza todo lo necesario para empezar a trabajar. Basta con descargarlo en el directorio de trabajo y ejecutarlo:

mkdir codeberg-pages-develop
cd codeberg-pages-develop
# coloca aquí setup_env.py
python setup_env.py

Qué hace paso a paso

1. Verifica que uv está instalado
2. Clona el repositorio en pages/  (rama main)
3. Crea el worktree de la rama src en src/
4. Crea el entorno virtual Python 3.12 en src/.venv/
5. Instala todas las dependencias desde requirements.txt
6. Comprueba si rsync está disponible (necesario para deploy.sh)

Al terminar muestra las instrucciones para activar el entorno y lanzar mkdocs serve.

Gestión del entorno con uv

El script usa uv en lugar de pip + venv. uv es un gestor de entornos y paquetes escrito en Rust, mucho más rápido y con mejor resolución de dependencias. Permite establecer la versión de Python a utilizar y mejora la gestión de dependencias.

# Instalar uv antes de ejecutar setup_env.py

# Windows
scoop install uv
# o
winget install --id=astral-sh.uv

# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

uv venv genera un entorno estándar compatible con cualquier herramienta que espere un venv convencional. Los scripts de despliegue existentes funcionan sin cambios.

Detección de requisitos

Si uv no está instalado, el script muestra las instrucciones de instalación y aborta. Lo mismo con rsync al final: avisa si no está disponible e indica cómo instalarlo según el sistema operativo.

2) Arquitectura de carpetas y ramas

El repositorio usa git worktrees para trabajar con dos ramas en carpetas separadas sin tener que cambiar de rama. Para poder desplegar la página también en GitHub pages se añade una tercera carpeta web que contendrá los archivos fuente de dicho despliegue..

graph LR
    subgraph Codeberg
        repo[("Repositorio\nichigar/pages")]
        repo -->|"rama main"| pages["pages/\n(HTML publicado)"]
        repo -->|"rama src"| src["src/\n(fuentes + scripts)"]
    end

    subgraph GitHub
        gh[("Repositorio\nichigar/web")]
        gh -->|"rama main"| web["web/\n(web/docs/ → HTML)"]
    end

    src -->|"deploy.py"| pages
    src -->|"deploy-github.py"| web

3) Scripts de despliegue multiplataforma

Los scripts .sh existentes necesitan bash y rsync, lo que dificulta su ejecución en Windows. Para simplificar el proceso se han añaden equivalentes en Python que funcionan en cualquier plataforma.

Flujo de despliegue

flowchart TD
    edit["✏️ Editar docs/"]
    commit["git commit + push\nrama src"]
    build["mkdocs build\n→ site/"]

    edit --> commit --> build

    build --> codeberg["🔄 sync site/ → pages/\ngit commit + push main"]
    build --> github["🔄 sync site/ → web/docs/\ngit commit + push"]

    codeberg --> pub1["🌐 Codeberg Pages"]
    github --> pub2["🌐 GitHub Pages"]

deploy.py (Codeberg Pages)

Replica la lógica de deploy.sh: commit en rama src, build con MkDocs, sincronización a ../pages/ y commit en rama main.

El sustituto de rsync --delete borra todo lo que haya en ../pages/ excepto .git y copia el contenido de site/:

def sync_site(src: Path, dst: Path) -> None:
    for item in dst.iterdir():
        if item.name == ".git":
            continue
        if item.is_dir():
            shutil.rmtree(item)
        else:
            item.unlink()
    for item in src.iterdir():
        dest = dst / item.name
        if item.is_dir():
            shutil.copytree(item, dest)
        else:
            shutil.copy2(item, dest)

deploy-github.py (GitHub Pages)

El repositorio github.com/ichigar/web aloja una segunda copia del sitio en su subcarpeta docs/. Para usarlo hay que tener el repo clonado como carpeta hermana:

# desde codeberg-pages-develop/
git clone https://github.com/ichigar/web ../web

Resumen de scripts

Script	Plataforma	Destino
deploy.sh	Linux / macOS	Codeberg Pages
deploy.py	Cualquiera	Codeberg Pages
deploy-github.sh	Linux / macOS	GitHub (web/docs/)
deploy-github.py	Cualquiera	GitHub (web/docs/)

El flujo de trabajo habitual no cambia:

cd src/
# editar docs/...
python deploy.py           # publica en Codeberg
python deploy-github.py    # publica en GitHub

Comentarios