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.

What have you tried? What hasn't worked? What resources have you consulted? — Daniel Mann
– Daniel Mann, Commented Jul 6, 2023 at 20:03
There is a misandurstanding here. These question are not easily answered on SO (or they require a more accurate wording that I don't yet have). If someone already know that's for the better. If not I'll share my findings so that the next beginner will find it as I always do like here: gis.stackexchange.com/questions/377222/…. Please don't close my questions, I'll populate the answers if nobody shows up. — Pierrick Rambaud
– Pierrick Rambaud, Commented Jul 6, 2023 at 21:38

Pierrick Rambaud · Accepted Answer · 2023-07-06 23:06:02Z

2

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.

answered Jul 6, 2023 at 23:06

Pierrick Rambaud

2,6882 gold badges29 silver badges75 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

user1911091 Over a year ago

Do you really have to create and pay a Azure web App ? Is it not possible to deploy documentation of the build artifact on the build pipeline? I mean doxygen and lcov are also static web pages and can also be attached to the build result

Pierrick Rambaud Feb 17 at 11:02

you can stop once the static website is created and send it as a build artificat, I see no problem there.

Collectives™ on Stack Overflow

how to deploy an html documentation page in devOps?

1 Answer 1

Prepare the static webApp

Create the documentation

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Prepare the static webApp

Create the documentation

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related