85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```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)
|
|
```
|
|
|
|
**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
|
|
|
|
```
|
|
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
|
|
```
|