Docs Hub Azure Pipelines

These are pipeline templates to make it easier to perform pipeline tasks on docs-hub.

sync-v1.yml

This adds the documentation branch of the repository to docs-hub:

• Adds the documentation branch as submodule to docs-hub
• Adds the navigation information to the docs-hub YAML page
• Creates a PR to the docs-hub repository

Parameters

Required

• docsBranch (string): Branch of the current repository used as the documentation branch.

• docsHubPath (string): Path in the docs hub to place the sourceBranch as submodule

• docsHubNavHeader (string): The navigation header to use for the index file of the documentation branch.

Optional

• docsHubNavSubheader (string): the navigation subheader to use for the index file of the documentation branch. No subheader is used if defined as empty string. Default is empty string.

• docsHubBranch (string): The branch of the docs-hub to update. Default is main.

• docsHubRepository (string): The repository name used to define the docs-hub as a resource. Default is docs-hub

• docsIndexFile (string): The index file in the documentation to add in the navigation. Default is index.html

• gitUser (string): The name of the git user to commit the changes. Default is docs-hub-pipeline.

• gitEmail (string): The email of the git user to commit the changes. Default is pipeline@azure.com.

• makePullRequest (boolean): Flag to create a pull request. Default is false.

• autoComplete (boolean): Flag to define if the pull request should automatically complete. Default is false

Example

The pipeline below is a basic example of the usage of the template.

name: Documentation Update

trigger:
  - main

pr: none

pool:
  vmImage: 'ubuntu-22.04'

variables:
  gitUser: Azure Pipeline
  gitEmail: pipeline@azure.com
  docsBranch: azure-docs

resources:
  repositories:
    # Add the docs hub repository as resource as this is required to sync
    # The value of the repository key should match the docsHubRepository
    # parameter of the sync template. The default value is docs-hub.
    - repository: docs-hub
      type: git
      name: docs-hub

    # Add this repository as a resource to be able to access the templates
    - repository: templates
      type: git
      name: template-azure-pipelines
      # The ref refers to the branch where the templates are in. If using a
      # template from a non-default branch, this must be set, otherwise this is
      # optional to define.
      ref: main

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

# This is the step to build the documentation. This varies depending on the
# tool and programming language used.
- 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

- template: docs-hub/sync-v1.yml@templates
  parameters:
    # Define the sync parameters

    # This is the branch of the source repository where the documentation is in
    docsBranch: $(docsBranch)

    # This is the path in docs path to embed the documentation branch as a
    # git submodule
    docsHubPath: docs/docs-hub/example-project

    # This are the header and subheader to use for the page in navigation.
    docsHubNavHeader: Docs Hub
    docsHubNavSubHeader: Example Project

    # This flag is set so the pipeline makes a Pull Request
    makePullRequest: true