=============================================== Publicación de Documentación Sphinx en Azure ===============================================

Introducción

Este manual describe el proceso completo para publicar documentación Sphinx (archivos .rst generados como HTML) en Azure Static Web Apps (SWA) usando la CLI. Incluye la creación del servicio, autenticación, instalación de herramientas, despliegue y verificación.

Requisitos previos

  • Cuenta corporativa Microsoft 365 activa (por ejemplo, hgasca@prodisys.com).

  • Acceso al portal Azure: https://portal.azure.com

  • Documentación generada localmente con Sphinx (carpeta build/html).

  • Permisos para crear recursos en la suscripción de Azure.

Creación del servicio Azure Static Web App

  1. Iniciar sesión en el portal de Azure: https://portal.azure.com

  2. En la barra de búsqueda, escribir Static Web Apps y seleccionar + Create.

  3. Completar los campos principales:

    • Subscription: Seleccionar la suscripción disponible (Free Trial o Prodisys Subscription).

    • Resource group: Crear uno nuevo, por ejemplo prodisys-docs.

    • Name: prodisys-docs.

    • Plan: Standard.

    • Region: Brazil South.

  4. En la sección Deployment details, seleccionar Other.

  5. En los campos de rutas:

    • App location: /

    • Output location: build/html

  6. Revisar y crear el recurso (Review + Create → Create).

  7. Una vez completado, Azure mostrará una URL temporal, por ejemplo:

https://prodisys-docs-xyz123.z01.web.core.windows.net

Instalación de la CLI de Azure

En sistemas Ubuntu/Debian:

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash az version

En Windows:

  1. Descargar desde: https://aka.ms/installazurecliwindows

  2. Ejecutar el instalador MSI y reiniciar PowerShell.

  3. Verificar instalación:

az version

Autenticación en Azure

Iniciar sesión en la cuenta corporativa desde la CLI:

az login

Esto abrirá el navegador predeterminado para autenticarse con Microsoft 365. Cuando la CLI muestre información de la suscripción, la conexión estará activa.

Instalación de la CLI de Static Web Apps

La CLI de Azure no incluye por defecto el comando de carga. Instalar la herramienta específica de SWA (requiere Node.js).

  1. Instalar NVM y Node LTS:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash export NVM_DIR=“\(HOME/.nvm" . "\)NVM_DIR/nvm.sh” nvm install –lts

  1. Instalar la CLI de SWA:

npm install -g @azure/static-web-apps-cli swa –version

Obtención del Token de Despliegue

  1. En el portal de Azure, abrir la aplicación prodisys-docs.

  2. En el menú izquierdo, seleccionar Deployment token.

  3. Copiar el token mostrado; se usará en el comando de despliegue.

Despliegue de la documentación

  1. Moverse a la carpeta raíz del proyecto (fuera de build/html):

cd ~/Documents/Prodisys/DOCUMENT_R2/docs

  1. Ejecutar el despliegue con el token:

swa deploy –app-location “.” –output-location “build/html” –deployment-token “” –env production

# Reemplazar por el valor copiado desde el portal.

  1. Esperar la confirmación:

Deployment complete

Verificación del sitio

  1. Abrir la URL temporal desde el portal Azure.

  2. Verificar que se cargue el sitio generado por Sphinx correctamente.

  3. En caso de errores de estilos, confirmar que se subió la carpeta completa que contiene index.html y las carpetas _static y _sources.

Actualizaciones posteriores

Cada vez que se ejecute make html para regenerar la documentación:

swa deploy –app-location “.” –output-location “build/html” –deployment-token “” –env production

El sitio se actualizará automáticamente.

Próximos pasos

Una vez publicada la documentación:

  1. Configurar el subdominio docs.prodisys.com con un registro CNAME.

  2. Activar la autenticación mediante Microsoft Entra ID (SSO).

  3. Restringir el acceso únicamente a usuarios autorizados.