Leopoldo Rodríguez
a91580e1af
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QCy5VHMVLkAmftYM6swWmx
101 lines
4.3 KiB
Markdown
101 lines
4.3 KiB
Markdown
# hbox-docs — sitio de documentación técnica del HBOX
|
|
|
|
Sitio **MkDocs Material** (español de México) + backend Flask: el **centro de mando** del proyecto
|
|
Drogheda en `https://drogheda.helgen.online`. Pendientes (kanban), ruta a producción, actas por unidad,
|
|
inventario, sitios, bitácora y los documentos que se publican (procedimientos, auditorías, ECOs,
|
|
manuales). Vive como **submódulo de Drogheda**, igual que el repo de KiCad.
|
|
|
|
**Regla: si no está en el sitio, no pasó.** Cada tarea termina aquí: su pendiente, su documento y, si
|
|
algo estorbó, una mejora. Para Claude: `CLAUDE.md` (dónde vive cada cosa y cómo se cambia).
|
|
|
|
## Flujo de trabajo
|
|
|
|
```bash
|
|
# 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/drogheda/hbox-docs/site (puerto 22)
|
|
# también copia el backend y baja la foto del tablero a _estado/
|
|
|
|
# 5. lotes de Claude para el tablero (si hay uno nuevo en backend/lotes/)
|
|
./scripts/tablero.sh revisar # qué cambiaría cada uno; no escribe nada
|
|
./scripts/tablero.sh aplicar # los aplica y baja la foto nueva
|
|
```
|
|
|
|
**Política de publicación:** solo se publica lo que está en la lista de
|
|
`scripts/sync-docs.sh`. Se publica lo que sirve al técnico o al estado de ingeniería
|
|
(procedimientos, actas, manuales, ECOs, auditorías de diseño y layout, guías de layout);
|
|
nada de finanzas, fundraising ni briefs comerciales. Para agregar un documento al sitio se
|
|
agrega a esa lista (y con eso queda auditado en git). Lo superado no se borra: baja a
|
|
«Referencia e histórico» con un banner que dice qué lo sustituye.
|
|
|
|
## Configuración del servidor (una sola vez)
|
|
|
|
En el servidor (`git.helgen.online` u otro), como root:
|
|
|
|
```bash
|
|
mkdir -p /srv/projects/drogheda/hbox-docs/site
|
|
chown -R leo:leo /srv/projects/drogheda/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 `drogheda.helgen.online`):
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name drogheda.helgen.online;
|
|
|
|
# ssl_certificate ... ; # certbot --nginx -d drogheda.helgen.online
|
|
# ssl_certificate_key ... ;
|
|
|
|
root /srv/projects/drogheda/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;
|
|
}
|
|
}
|
|
```
|
|
|
|
```bash
|
|
ln -s /etc/nginx/sites-available/hbox-docs /etc/nginx/sites-enabled/
|
|
nginx -t && systemctl reload nginx
|
|
```
|
|
|
|
Los técnicos entran a `https://drogheda.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
|
|
|
|
```
|
|
CLAUDE.md reglas para Claude: dónde vive cada cosa del sitio y cómo se cambia
|
|
mkdocs.yml configuración del sitio (nav, tema, español, hooks)
|
|
docs/ contenido publicado (lo sincronizado por sync-docs.sh + páginas propias del sitio)
|
|
docs/datos/proyecto.json ruta a producción, tarjeta por versión, fechas y sitios de la página de inicio
|
|
overrides/, hooks/ plantillas del tema Helgen y ganchos de MkDocs (documentos recientes, versión de CSS/JS)
|
|
backend/ app.py (actas, pendientes, inventario, sitios, equipo, enfoque, actividad) + servicio
|
|
backend/tablero.py foto del tablero y lotes de Claude (lo llama scripts/tablero.sh)
|
|
backend/lotes/ lotes de cambios al tablero, uno por tarea terminada (formato en su README)
|
|
scripts/sync-docs.sh lista curada Drogheda → docs/ (la política de publicación)
|
|
scripts/deploy.sh mkdocs build --strict + rsync del sitio y del backend + foto del tablero
|
|
scripts/tablero.sh foto / revisar / aplicar desde la Mac
|
|
_estado/ foto del tablero (tablero.json, tablero.md); fuera de git
|
|
```
|