how to deploy an html documentation page in devOps?

Question

My devOps pipeline is building the documentation of my python lib. This documentation is built with Sphinx so I export the whole docs/_build folder as an artifact but I don't know how to deploy it as a documentation website.

Here is my doc.yaml:

trigger:
  branches:
    include:
      - main

pool:
  vmImage: windows-latest

steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: "3.10"
    displayName: "Use Python 3.10"

  - script: python -m pip install nox
    displayName: "Install dependencies"

  - script: nox -s docs
    displayName: "Build static docs"

  - task: PublishBuildArtifacts@1
    displayName: "Publish HTML"
    inputs:
      pathToPublish: "./docs/_build/html/"
      artifactName: "documentation"

Note that the build is a static website.

Answer 1

Prepare the static webApp

The first step to deploy your static resource is to create the web application where the files will be deployed.

To create a static web App, first go to the Azure portal: https://portal.azure.com/

Please follow the instruction from this medium article as the process is not automated at all an require to click on multiple buttons. You can also refer to this answer](how to deploy as a web app the html static website generated by pytest in devops?) were instruction have been written down.

Once your static app is ready, save the token.

Create the documentation

No need to create an artifcat as you use the same pipeline to build and publish. Simply run your favorit sphinx build command:

- script: make html # it can be wrapped in nox or directly use stb
  displayName: "Build static docs"

If you respected the convention from Sphinx-quickstart, the documentation should be located in docs/_build/html. Create a extra step to send this folder to the application:

- task: AzureStaticWebApp@0
    inputs:
      app_location: "/docs/_build/html"
      azure_static_web_apps_api_token: $(DEPLOYMENT_TOKEN)

Don't forget to add the DEPLOYMENT_TOKEN that we saved earlier in the pipeline variable. Run the pipeline and the documentation will be available in the Azure app.