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

.. contents:: 
   :depth: 2 
   :local:

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:

.. code-block:: bash

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

Instalación de la CLI de Azure
==============================

En sistemas Ubuntu/Debian:

.. code-block:: bash

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:

.. code-block:: bash

az version

Autenticación en Azure
======================

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

.. code-block:: bash

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:

.. code-block:: bash

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

2. Instalar la CLI de SWA:

.. code-block:: bash

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``):

.. code-block:: bash

cd ~/Documents/Prodisys/DOCUMENT_R2/docs

2. Ejecutar el despliegue con el token:

.. code-block:: bash

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

# Reemplazar por el valor copiado desde el portal.

3. Esperar la confirmación:

.. code-block:: bash

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:

.. code-block:: bash

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.