Chaminda's DevOps Journey with MSFT: Publish Ascii Documentation to Confluence via Azure Pipelines

We can use AsciiDoc to write technical documentation. However, confluence is a popular wiki to keep the documentation related to software projects. In this blog let's look at how to publish AsciiDoc documentation in a repo to Confluence via Azure DevOps pipelines.

There are few useful extensions in VS code that you can use for ascii docs.

First let's create some sample Ascii docs. See example below.

Architecture.adoc the main document containing other docs.

// header file for arc42-template,
// including all help texts
//
// ====================================

// configure EN settings for asciidoc
include::src/config.adoc[]
:doctype: book
= My Demo Architecture Doc
:revnumber: 1.0 EN
:revdate: 16 Ocober 2024
:revremark: (optional remarks)
// toc-title definition MUST follow document title without blank line!
:toc-title: Table of Contents

This is a basic AsciiDoc document by Chaminda.

// horizontal line
'''

// numbering from here on
:numbered:

<<<
// 1. Introduction
include::src/01_introduction.adoc[]

<<<
// 2. System Overview
include::src/02_system_overview.adoc[]

config.adoc config settings.

// asciidoc settings for EN (English)
// ==================================
:toc-title: table of contents

// enable table-of-contents
:toc:

// where are images located?
:imagesdir: ./images

01_introduction.adoc Intro document.

ifndef::imagesdir[:imagesdir: ../images]

[[section-introduction]]
== Introduction

This is demo project introduction.

02_system_overview.adoc Overview documentation. Note here we have reffered to a diagram.

ifndef::imagesdir[:imagesdir: ../images]

[[section-system-overview]]
== System Overview

=== Demo Diagram

[umlet]
....

include::diagrams/demodiagram.uxf[]

....

demodiagram.uxf digram is created with umllet.

Let's create a placeholder page in confluence for the documents to be published. My spcae here is having Id DP01. And I have a page created and the Id of it is 2785281. We have to create a page at root level off the space to avoid other pages from getting overwiitten or deleted. Note that there are other docs added manually in the spcace and they should not be overwritten when we run the pipeline.

Then we have to create an API key that needs to be used for updating the docs via pipeline. You can find conflunece documentation here on how to create an API key.

Create two variables in Azure DevOps variable group for the user name and password (the API key we generated in confluence) as shown below.

Then lets create a docker file which will use confluencepublisher/confluence-publisher and install umllet in it as our docs use umlet digrams.

Docker file (pipelines\dockerfiles\confluence_publisher.Dockerfile) umlet installation below is copied from dockerfile here.

FROM confluencepublisher/confluence-publisher:0.23.0

RUN apk add --no-cache curl

ARG umlet_version="15.1"
# The umlet zip contains a camelcase directory :-|
ENV UMLET_HOME="${UMLET_HOME:-/usr/local/Umlet}"
# The umlet extension try to find 'umlet' in PATH and need the 'umlet.jar' in same directory :-|
ENV PATH="${UMLET_HOME:-/usr/local/Umlet}:${PATH}"
ENV UMLET_JAVA_OPTS="-Djava.awt.headless=true"
# Umlet download URL uses inconsistent version formats :-|
RUN curl -S -s -o ${TMPDIR}/umlet.zip https://www.umlet.com/download/umlet_${umlet_version//./_}/umlet-standalone-${umlet_version}.zip \
    && unzip -d /usr/local ${TMPDIR}/umlet.zip "*.jar" "*.sh"\
    && rm -f ${TMPDIR}/umlet.zip \
    && ln -snf "${UMLET_HOME}/umlet.sh" "${UMLET_HOME}/umlet"

Then we can define a pipeline job as shown below to publish the documentation. Note that we have used the correct confluence Url, space key and the page id (ANCESTOR_ID). We have use publishing strategy as REPLACE_ANCESTOR and that will replace the docs. The other option to use is APPEND_TO_ANCESTOR.

Pipeline job (pipelines\templates\jobs\publish_docs.yml)

jobs:
  - job: publish_docs
    workspace:
        clean: all
    displayName: 'Publish Docs'
    pool:
      vmImage: ubuntu-22.04
    steps:
      - checkout: self
        fetchDepth: 1
        clean: true
        persistCredentials: true

      - task: Bash@3
        displayName: 'Publish architecture docs'
        inputs:
          workingDirectory: '$(System.DefaultWorkingDirectory)'
          targetType: 'inline'
          script: |
            cd pipelines/dockerfiles;
            docker pull confluencepublisher/confluence-publisher:0.23.0;
            docker build --no-cache -t chconfpub:dev --progress=plain -f confluence_publisher.Dockerfile .;
            docker image ls;

            docker run --rm -v $(System.DefaultWorkingDirectory)/docs/architecture:/var/asciidoc-root-folder \
              -e ROOT_CONFLUENCE_URL=https://chamindac.atlassian.net/wiki \
              -e SKIP_SSL_VERIFICATION=false \
              -e USERNAME=$(confluence_username) \
              -e PASSWORD=$(confluence_password) \
              -e SPACE_KEY=DP01 \
              -e ANCESTOR_ID=2785281 \
              -e PUBLISHING_STRATEGY=REPLACE_ANCESTOR \
              -e ORPHAN_REMOVAL_STRATEGY=REMOVE_ORPHANS \
              chconfpub:dev

            docker image rm -f chconfpub:dev;
            docker image rm -f confluencepublisher/confluence-publisher:0.23.0;
            docker image ls;

Pipeline (pipelines\publish_docs.yml)

trigger:
  branches:
    include:
      - develop   
  paths:
    include:
      - docs

name: $(SourceBranchName)_$(Date:yyyyMMdd)$(Rev:r)

variables:
  - template: templates/vars/pipeline_vars.yml
  - group: "dev-common"

jobs:
  - template: templates/jobs/publish_docs.yml