Using Doctor on Azure DevOps to generate your documentation

February 26, 2021

GitHub Actions is hot these days, but still, Azure DevOps is being used in many companies, and I do as well. Doctor a tool for publishing your markdown documentation on SharePoint, works nicely on Azure DevOps as well.

Info I will use the doctor sample as the blueprint for this article.

The credentials

To start, you need to choose how you will publish your documentation to SharePoint. Doctor allows three types of authentication.

  1. Certificate authentication
  2. Username and password
  3. Device code

The third option is only preferred when using it on your local machine. When you want to use certificate authentication, you need to do some steps before making use of it.

Important Things to do before you can use certificate authentication: prerequisites for certificate authentication.

Using the credentials

On Azure DevOps, I recommend you make use of a variable group to connect to an Azure Key Vault. That way, all your secrets are secure and easy to be changed from one place.

Info Tobias Zimmergren wrote an excellent article about this: using Azure Key Vault Secrets from your Azure DevOps pipelines

Using a variable group is always a good idea; you do not need to manage your variables in your pipelines.

Azure DevOps variable group
Azure DevOps variable group

The pipeline

The pipeline itself is relatively straightforward — the azure-pipelines.yml file contents look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
trigger:
- main
- dev

variables:
  - group: doctor-sharepoint

stages:
- stage: 'publish'
  displayName: 'Publish to SharePoint'
  jobs:
  - job: 'mkdocs_build'    
    displayName: 'Building Documentation'
    pool:
      vmImage: ubuntu-latest
    steps:
      - script: |
          debug=""
          if [[ $(System.Debug) = true ]]; then
            debug="--debug"
          fi

          cleanStart=""
          if [[ $(build.SourceBranchName) = "main" ]]; then
            cleanStart="--cleanStart --confirm"
          fi
          
          sudo npm i @estruyf/[email protected] -g
          doctor publish --auth certificate --certificateBase64Encoded $(CERTBASE64) --password $(CERTPASSWORD) --appId $(APPID) --tenant $(TENANT) --url $(URL) $cleanStart $debug
        displayName: 'Publish via Doctor'

Under the variables property, the variable group called doctor-sharepoint in my case gets retrieved, which includes all the required environment variables.

The pipeline will get triggered whenever there is a push to the main or dev branch and does a clean-up first on main. If you set the debug system variable to true. Doctor will automatically run in debug mode, which gives you extra logging.

Running the pipeline

Running the pipeline on Azure DevOps will give you the following result:

Azure DevOps - Publish pipeline
Azure DevOps - Publish pipeline

Comments

comments powered by Disqus