Skip to content

Commit d287db8

Browse files
author
GitHub Actions
committed
ci: Add hardware documentation workflow and update build workflow
Workflow Updates: - Modified build_docs.yml with latest improvements - Added new copy-hardware-docs.yml workflow for hardware documentation automation - Added workflow scripts for hardware documentation processing New Files: - .github/workflows/copy-hardware-docs.yml: Automated hardware docs deployment - .github/workflows/scripts/: Supporting scripts for workflow automation These changes enhance the CI/CD pipeline with dedicated hardware documentation handling and improved automation for documentation deployment.
1 parent 307a67d commit d287db8

File tree

6 files changed

+826
-3
lines changed

6 files changed

+826
-3
lines changed

‎.github/workflows/build_docs.yml‎

Lines changed: 47 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,14 @@ jobs:
4848
env:
4949
REPO_NAME: ${{ github.event.repository.name }}
5050
run: |
51+
# Backup hardware documentation if it exists
52+
if [ -d "docs/hardware" ]; then
53+
echo "Backing up hardware documentation..."
54+
mv docs/hardware /tmp/hardware_backup
55+
mv docs/hardware.html /tmp/hardware.html.backup 2>/dev/null || true
56+
fi
57+
58+
# Clean docs/ directory (except hardware)
5159
rm -rf docs
5260
mkdir -p docs
5361
@@ -62,6 +70,13 @@ jobs:
6270
# HTML generado por Sphinx
6371
cp -r software/sphinx/docs/* docs/
6472
73+
# Restore hardware documentation if it was backed up
74+
if [ -d "/tmp/hardware_backup" ]; then
75+
echo "Restoring hardware documentation..."
76+
mv /tmp/hardware_backup docs/hardware
77+
mv /tmp/hardware.html.backup docs/hardware.html 2>/dev/null || true
78+
fi
79+
6580
# Permitir archivos especiales en GitHub Pages
6681
touch docs/.nojekyll
6782
@@ -73,7 +88,36 @@ jobs:
7388
run: |
7489
git config --global user.name "GitHub Actions"
7590
git config --global user.email "actions@github.com"
76-
git pull origin main
91+
92+
# Check if there are changes to commit
7793
git add docs/
78-
git commit -m "Deploy full documentation and product brief [skip ci]" || echo "No changes"
79-
git push origin main
94+
if git diff --staged --quiet; then
95+
echo "No changes to commit"
96+
exit 0
97+
fi
98+
99+
# Commit changes
100+
git commit -m "Deploy full documentation and product brief [skip ci]"
101+
102+
# Try to push, if fails pull and retry
103+
max_retries=3
104+
for i in $(seq 1 $max_retries); do
105+
if git push origin main; then
106+
echo "Successfully pushed!"
107+
exit 0
108+
fi
109+
110+
echo "Push failed, attempt $i of $max_retries"
111+
echo "Pulling latest changes..."
112+
113+
# Pull with merge strategy
114+
git pull --no-rebase --no-edit origin main || {
115+
echo "Pull failed, forcing merge with ours strategy for docs/"
116+
git checkout --ours docs/
117+
git add docs/
118+
git commit -m "Merge: Resolve conflicts keeping our docs/ [skip ci]" || true
119+
}
120+
done
121+
122+
echo "Failed to push after $max_retries attempts"
123+
exit 1

‎.github/workflows/copy-hardware-docs.yml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
name: Copy Hardware Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- 'hardware/**'
8+
workflow_dispatch: # Permite ejecutar manualmente
9+
10+
permissions:
11+
contents: write
12+
13+
jobs:
14+
copy-hardware-docs:
15+
runs-on: ubuntu-latest
16+
17+
steps:
18+
- name: Checkout repository
19+
uses: actions/checkout@v4
20+
with:
21+
token: ${{ secrets.GITHUB_TOKEN }}
22+
23+
- name: Set up Python
24+
uses: actions/setup-python@v4
25+
with:
26+
python-version: '3.9'
27+
28+
- name: Install dependencies
29+
run: |
30+
python -m pip install --upgrade pip
31+
pip install Jinja2
32+
33+
- name: Clean previous hardware documentation
34+
run: |
35+
chmod +x .github/workflows/scripts/clean_docs.sh
36+
.github/workflows/scripts/clean_docs.sh
37+
38+
- name: Copy hardware files and generate HTML
39+
run: |
40+
chmod +x .github/workflows/scripts/build_docs.sh
41+
.github/workflows/scripts/build_docs.sh
42+
43+
- name: Add hardware link to Sphinx docs
44+
run: |
45+
chmod +x .github/workflows/scripts/add_hardware_link.sh
46+
.github/workflows/scripts/add_hardware_link.sh
47+
48+
- name: Commit and push changes
49+
if: github.event_name != 'pull_request'
50+
run: |
51+
git config --local user.email "action@github.com"
52+
git config --local user.name "GitHub Action"
53+
54+
# Check if there are changes to commit
55+
git add docs/
56+
if git diff --staged --quiet; then
57+
echo "No changes to commit"
58+
exit 0
59+
fi
60+
61+
# Commit changes
62+
git commit -m "Auto-update hardware documentation [skip ci]"
63+
64+
# Try to push, if fails pull and retry
65+
max_retries=3
66+
for i in $(seq 1 $max_retries); do
67+
if git push origin main; then
68+
echo "Successfully pushed!"
69+
exit 0
70+
fi
71+
72+
echo "Push failed, attempt $i of $max_retries"
73+
echo "Pulling latest changes..."
74+
75+
# Pull with merge strategy
76+
git pull --no-rebase --no-edit origin main || {
77+
echo "Pull failed, forcing merge with ours strategy for docs/"
78+
git checkout --ours docs/
79+
git add docs/
80+
git commit -m "Merge: Resolve conflicts keeping our docs/ [skip ci]" || true
81+
}
82+
done
83+
84+
echo "Failed to push after $max_retries attempts"
85+
exit 1

‎.github/workflows/scripts/add_hardware_link.sh‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
#!/bin/bash
2+
3+
# Script para agregar enlace a hardware.html en el index.html de Sphinx
4+
# Ubicación: .github/workflows/scripts/add_hardware_link.sh
5+
# Uso: .github/workflows/scripts/add_hardware_link.sh
6+
7+
set -e # Salir si hay algún error
8+
9+
echo "🔗 Agregando enlace a documentación de hardware en Sphinx..."
10+
11+
# Obtener la ruta del directorio del proyecto
12+
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
13+
cd "$PROJECT_DIR"
14+
15+
INDEX_FILE="docs/index.html"
16+
17+
# Verificar que existe el index.html de Sphinx
18+
if [ ! -f "$INDEX_FILE" ]; then
19+
echo "ℹ️ Archivo $INDEX_FILE no existe aún"
20+
echo " El enlace se agregará cuando se genere la documentación de Sphinx"
21+
exit 0
22+
fi
23+
24+
# Verificar que hardware.html existe
25+
if [ ! -f "docs/hardware.html" ]; then
26+
echo "⚠️ Advertencia: docs/hardware.html no existe"
27+
exit 0
28+
fi
29+
30+
# Verificar si ya existe el enlace para evitar duplicados
31+
if grep -q "hardware.html" "$INDEX_FILE"; then
32+
echo "✓ El enlace a hardware.html ya existe en index.html"
33+
exit 0
34+
fi
35+
36+
# Crear un script de inyección HTML
37+
HARDWARE_LINK='<div style="position: fixed; top: 80px; right: 20px; z-index: 1000;"><a href="hardware.html" class="btn btn-sm" style="background-color: #6366f1; color: white; padding: 8px 16px; border-radius: 6px; text-decoration: none; box-shadow: 0 2px 4px rgba(0,0,0,0.1); display: inline-flex; align-items: center; gap: 8px; font-weight: 500;" title="Ver documentación de hardware"><svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16"><path d="M5 0a.5.5 0 0 1 .5.5V2h1V.5a.5.5 0 0 1 1 0V2h1V.5a.5.5 0 0 1 1 0V2h1V.5a.5.5 0 0 1 1 0V2A2.5 2.5 0 0 1 14 4.5h1.5a.5.5 0 0 1 0 1H14v1h1.5a.5.5 0 0 1 0 1H14v1h1.5a.5.5 0 0 1 0 1H14v1h1.5a.5.5 0 0 1 0 1H14a2.5 2.5 0 0 1-2.5 2.5v1.5a.5.5 0 0 1-1 0V14h-1v1.5a.5.5 0 0 1-1 0V14h-1v1.5a.5.5 0 0 1-1 0V14h-1v1.5a.5.5 0 0 1-1 0V14A2.5 2.5 0 0 1 2 11.5H.5a.5.5 0 0 1 0-1H2v-1H.5a.5.5 0 0 1 0-1H2v-1H.5a.5.5 0 0 1 0-1H2v-1H.5a.5.5 0 0 1 0-1H2A2.5 2.5 0 0 1 4.5 2V.5A.5.5 0 0 1 5 0m-.5 3A1.5 1.5 0 0 0 3 4.5v7A1.5 1.5 0 0 0 4.5 13h7a1.5 1.5 0 0 0 1.5-1.5v-7A1.5 1.5 0 0 0 11.5 3zM5 6.5A1.5 1.5 0 0 1 6.5 5h3A1.5 1.5 0 0 1 11 6.5v3A1.5 1.5 0 0 1 9.5 11h-3A1.5 1.5 0 0 1 5 9.5zM6.5 6a.5.5 0 0 0-.5.5v3a.5.5 0 0 0 .5.5h3a.5.5 0 0 0 .5-.5v-3a.5.5 0 0 0-.5-.5z"/></svg> Hardware</a></div>'
38+
39+
# Crear backup
40+
cp "$INDEX_FILE" "${INDEX_FILE}.backup"
41+
42+
# Inyectar el enlace justo después de <body>
43+
# Usando sed para insertar después de la etiqueta <body>
44+
sed -i "/<body>/a\\
45+
$HARDWARE_LINK" "$INDEX_FILE"
46+
47+
# Verificar que la inyección fue exitosa
48+
if grep -q "hardware.html" "$INDEX_FILE"; then
49+
echo "✅ Enlace agregado exitosamente a $INDEX_FILE"
50+
rm "${INDEX_FILE}.backup"
51+
else
52+
echo "❌ Error al agregar el enlace, restaurando backup"
53+
mv "${INDEX_FILE}.backup" "$INDEX_FILE"
54+
exit 1
55+
fi
56+
57+
echo "✨ ¡Proceso completado!"

‎.github/workflows/scripts/build_docs.sh‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/bin/bash
2+
3+
# Script para ejecutar el proceso de copia de documentación de hardware
4+
# Ubicación: .github/workflows/scripts/build_docs.sh
5+
# Uso: .github/workflows/scripts/build_docs.sh
6+
7+
set -e # Salir si hay algún error
8+
9+
echo "🔨 Iniciando construcción de documentación de hardware..."
10+
11+
# Obtener la ruta del directorio del proyecto (3 niveles arriba desde .github/workflows/scripts)
12+
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
13+
cd "$PROJECT_DIR"
14+
15+
echo "📂 Directorio del proyecto: $PROJECT_DIR"
16+
17+
# Verificar que Python está disponible
18+
if ! command -v python3 &> /dev/null; then
19+
echo " Python3 no está instalado"
20+
exit 1
21+
fi
22+
23+
# Crear directorio temporal para el entorno virtual
24+
TEMP_VENV=$(mktemp -d)
25+
echo " Creando entorno virtual temporal en: $TEMP_VENV"
26+
27+
# Crear entorno virtual
28+
python3 -m venv "$TEMP_VENV"
29+
30+
# Activar entorno virtual
31+
echo " Activando entorno virtual..."
32+
source "$TEMP_VENV/bin/activate"
33+
34+
# Instalar dependencias
35+
echo " Instalando dependencias..."
36+
pip install --upgrade pip --quiet
37+
pip install Jinja2 --quiet
38+
39+
# Ejecutar script de copia
40+
echo "📋 Ejecutando script de copia..."
41+
python3 .github/workflows/scripts/copy_hardware_docs.py
42+
43+
# Limpiar entorno virtual temporal
44+
echo " Limpiando entorno virtual temporal..."
45+
deactivate
46+
rm -rf "$TEMP_VENV"
47+
48+
# Verificar que los archivos se generaron correctamente
49+
if [ -f "docs/hardware.html" ]; then
50+
echo "✅ Documentación de hardware generada exitosamente!"
51+
echo "📄 Archivos generados:"
52+
echo " - docs/hardware.html (página de hardware)"
53+
echo " - docs/hardware/ (archivos copiados)"
54+
55+
# Mostrar estadísticas
56+
if [ -d "docs/hardware" ]; then
57+
file_count=$(find docs/hardware -type f | wc -l)
58+
echo "📊 Total de archivos copiados: $file_count"
59+
fi
60+
61+
# Verificar que la documentación de Sphinx sigue intacta
62+
if [ -f "docs/index.html" ]; then
63+
echo "💾 Documentación de Sphinx preservada: OK"
64+
else
65+
echo "⚠️ Nota: docs/index.html no existe (la documentación de Sphinx aún no ha sido generada)"
66+
fi
67+
68+
else
69+
echo "❌ Error: No se pudo generar la documentación de hardware"
70+
exit 1
71+
fi
72+
73+
echo "✨ ¡Proceso completado!"
74+
echo "📖 Documentación de hardware: docs/hardware.html"
75+
echo "📖 Documentación de Sphinx: docs/index.html"

‎.github/workflows/scripts/clean_docs.sh‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/bin/bash
2+
3+
# Script para limpiar archivos generados de documentación de hardware
4+
# Ubicación: .github/workflows/scripts/clean_docs.sh
5+
# Uso: .github/workflows/scripts/clean_docs.sh
6+
#
7+
# IMPORTANTE: Este script solo limpia la documentación de hardware
8+
# (docs/hardware/ y hardware.html) preservando la documentación de Sphinx
9+
10+
set -e # Salir si hay algún error
11+
12+
echo "🧹 Limpiando documentación de hardware generada..."
13+
14+
# Obtener la ruta del directorio del proyecto (3 niveles arriba desde .github/workflows/scripts)
15+
PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
16+
cd "$PROJECT_DIR"
17+
18+
echo "📂 Directorio del proyecto: $PROJECT_DIR"
19+
20+
# Verificar que el directorio docs existe
21+
if [ ! -d "docs" ]; then
22+
echo "ℹ️ Directorio docs no existe, no hay nada que limpiar"
23+
exit 0
24+
fi
25+
26+
# Contar archivos/directorios antes de limpiar
27+
hardware_files_before=0
28+
hardware_dirs_before=0
29+
30+
if [ -d "docs/hardware" ]; then
31+
hardware_files_before=$(find docs/hardware -type f 2>/dev/null | wc -l)
32+
hardware_dirs_before=$(find docs/hardware -type d 2>/dev/null | wc -l)
33+
fi
34+
35+
if [ -f "docs/hardware.html" ]; then
36+
hardware_files_before=$((hardware_files_before + 1))
37+
fi
38+
39+
echo "📊 Archivos de hardware antes de limpiar: $hardware_files_before"
40+
41+
# Eliminar solo los archivos de documentación de hardware
42+
# Preservar toda la documentación de Sphinx
43+
echo "🗑️ Eliminando documentación de hardware..."
44+
45+
# Eliminar directorio docs/hardware/
46+
if [ -d "docs/hardware" ]; then
47+
rm -rf docs/hardware
48+
echo " ✓ Eliminado: docs/hardware/"
49+
fi
50+
51+
# Eliminar archivo hardware.html si existe
52+
if [ -f "docs/hardware.html" ]; then
53+
rm -f docs/hardware.html
54+
echo " ✓ Eliminado: docs/hardware.html"
55+
fi
56+
57+
# Contar archivos después de limpiar
58+
hardware_files_after=0
59+
60+
if [ -d "docs/hardware" ]; then
61+
hardware_files_after=$(find docs/hardware -type f 2>/dev/null | wc -l)
62+
fi
63+
64+
if [ -f "docs/hardware.html" ]; then
65+
hardware_files_after=$((hardware_files_after + 1))
66+
fi
67+
68+
# Mostrar estadísticas
69+
files_deleted=$((hardware_files_before - hardware_files_after))
70+
71+
echo "✅ Eliminados: $files_deleted archivo(s) de hardware"
72+
echo "💾 Documentación de Sphinx preservada"
73+
74+
# Verificar que la documentación de Sphinx sigue intacta
75+
if [ -f "docs/index.html" ]; then
76+
echo "✓ Documentación de Sphinx: OK (index.html presente)"
77+
else
78+
echo "⚠️ Advertencia: docs/index.html no encontrado (puede ser normal si aún no se ha generado)"
79+
fi
80+
81+
echo "✨ Limpieza completada!"

0 commit comments

Comments
 (0)