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

El sistema de publicación de mis apuntes y recursos estrena 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.

El punto de partida¶

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

Salida de setup_env.py ejecutándose con éxito

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. Fija Python 3.12, versión con wheels precompiladas para todas las dependencias del proyecto.

# 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

Internamente el script hace:

run(["uv", "venv", "--python", "3.12", str(venv)])
run(["uv", "pip", "install", "--python", str(venv), "-r", str(req_file)], cwd=src)

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. Con el despliegue en GitHub se añade una tercera carpeta hermana.

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 los hace incómodos en Windows. Se han añadido 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 disponibles¶

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