hbox-docs/README.md

hbox-docs — sitio de documentación técnica del HBOX

Sitio MkDocs Material (español) con el subconjunto de documentación del proyecto Drogheda que los técnicos necesitan: procedimientos de banco, montaje/arneses, diagnóstico remoto y la guía Git. Vive como submódulo de Drogheda, igual que el repo de KiCad.

Flujo de trabajo

# 1. actualizar el contenido desde Drogheda (la lista curada vive en el script)
./scripts/sync-docs.sh

# 2. ver el sitio en local
pip install mkdocs-material        # una sola vez
mkdocs serve                        # http://127.0.0.1:8000

# 3. commit + push de este repo (y bump del submódulo en Drogheda)

# 4. publicar al servidor
./scripts/deploy.sh                 # leo@git.helgen.online:/srv/projects/hbox-docs/site (puerto 22)

Política de publicación: solo se publica lo que está en la lista de scripts/sync-docs.sh. Nada de finanzas, briefs de diseño ni auditorías EMC; para agregar un documento al sitio se agrega a esa lista (y con eso queda auditado en git).

Configuración del servidor (una sola vez)

En el servidor (git.helgen.online u otro), como root:

mkdir -p /srv/projects/hbox-docs/site
chown -R leo:leo /srv/projects/hbox-docs           # el usuario con el que hace rsync deploy.sh

# usuarios para los técnicos (HTTP Basic)
apt install -y apache2-utils
htpasswd -c /etc/nginx/hbox-docs.htpasswd luz
htpasswd    /etc/nginx/hbox-docs.htpasswd leo

Bloque de nginx (por ejemplo /etc/nginx/sites-available/hbox-docs, con el certificado que ya tenga el servidor o uno nuevo de certbot para docs.helgen.online):

server {
    listen 443 ssl;
    server_name docs.helgen.online;

    # ssl_certificate     ... ;   # certbot --nginx -d docs.helgen.online
    # ssl_certificate_key ... ;

    root /srv/projects/hbox-docs/site;
    index index.html;

    auth_basic           "Helgen HBOX docs";
    auth_basic_user_file /etc/nginx/hbox-docs.htpasswd;

    location / {
        try_files $uri $uri/ =404;
    }
}

ln -s /etc/nginx/sites-available/hbox-docs /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

Los técnicos entran a https://docs.helgen.online con su usuario y contraseña. Alternativa sin subdominio: servirlo como location /hbox/ dentro del server block existente, con el mismo auth_basic.

Estructura

mkdocs.yml            configuración del sitio (nav, tema, español)
docs/                 contenido publicado (generado por sync-docs.sh + index.md)
scripts/sync-docs.sh  lista curada Drogheda → docs/
scripts/deploy.sh     mkdocs build --strict + rsync al servidor