Continuous Integration

Docs Hub

The docs hub repository has its CI pipeline for deploying changes to main into a website. There is no need to change this pipeline when adding a new project.

Other Projects

After building its own documentation, the projects need to update the docs hub repository from the CI.

An Azure Pipeline template is provided to update the docs hub. Note that the template clones the docs-hub repository and thus may affect the folder structure in the worker.

Below is an example pipeline. The highlighted parts are the parts needed to sync the project documentation with docs hub.

.azure-pipelines/documentation.yml

name: Documentation Update

trigger:
  - main
  - master

pr: none

pool:
  vmImage: 'ubuntu-22.04'

variables:
# Pipeline variables. Git settings and the branch to push the generated
# documentation
  gitUser: Azure Pipeline
  gitEmail: pipeline@azure.com
  docsBranch: azure-docs

resources:
  repositories:
  # The docs-hub repository and the template repository are added as resource
    - repository: docs-hub
      type: git
      name: docs-hub

    - repository: templates
      type: git
      name: template-azure-pipelines

steps:
- checkout: self
  clean: 'true'
  persistCredentials: 'true'

# This is the step for generating the documentation. This varies depending on
# the tool and programming language. Here, mkdocs is used to build the
# documentation and update the branch with the documentation
- script: |
    cd $(Build.Repository.Name)

    git config user.email "$(gitUser)"
    git config user.name "$(gitEmail)"

    pip install -r requirements.txt
    git fetch origin $(docsBranch)
    mkdocs gh-deploy

# Usage of the template. Check the template documentation for more details.
- template: docs-hub/sync-v1.yml@templates
  parameters:
    docsBranch: $(docsBranch)
    docsHubPath: docs/docs-hub/example-project
    docsHubNavHeader: Docs Hub
    docsHubNavSubHeader: Example Project
    makePullRequest: true