Setting Up the Docusaurus Documentation Pipeline

This guide explains how to configure and use the Azure DevOps pipeline scripts for generating and publishing Docusaurus-compatible documentation for the Jupiter Market Elastic - Comparable Deals project.

Prerequisites

• Azure DevOps repository with pipeline permissions.
• .NET 9 SDK installed on the build agent.
• Elastic Cloud account and API key (for documentation indexing).
• The following scripts in your repository:
  • scripts/generate-docs.ps1
  • scripts/index-docs-to-elastic.ps1

Pipeline Overview

The pipeline performs the following steps:

1. Restores and builds the .NET project (generates XML docs).
2. Runs generate-docs.ps1 to convert XML and Markdown to Docusaurus format.
3. Runs index-docs-to-elastic.ps1 to index documentation into Elastic Cloud.
4. Commits and pushes the generated documentation to the repository.

Required Pipeline Variables

Set these variables in your Azure DevOps pipeline (as secrets if appropriate):

• ELASTIC_CLOUD_ID: Your Elastic Cloud deployment Cloud ID.
• ELASTIC_API_KEY: Your Elastic Cloud API key.

YAML Pipeline Example

Below is a simplified version of the pipeline configuration:

trigger:
  branches:
    include:
      - main
      - develop
  paths:
    include:
      - docs/**
      - Jupiter.Market.Elastic.Comparables/**/*.cs

pool:
  vmImage: 'ubuntu-latest'

variables:
  buildConfiguration: 'Release'

stages:
- stage: BuildAndGenerateDocs
  jobs:
  - job: BuildAndGenerate
    steps:
    - checkout: self
      persistCredentials: true

    - task: UseDotNet@2
      inputs:
        packageType: 'sdk'
        version: '9.0.x'

    - task: DotNetCoreCLI@2
      inputs:
        command: 'restore'
        projects: '**/*.csproj'

    - task: DotNetCoreCLI@2
      inputs:
        command: 'build'
        projects: '**/*.csproj'
        arguments: '--configuration $(buildConfiguration) --no-restore'

    - task: PowerShell@2
      displayName: 'Generate Docusaurus-compatible documentation'
      inputs:
        targetType: 'filePath'
        filePath: '$(Build.SourcesDirectory)/scripts/generate-docs.ps1'
        arguments: >
          -RepoRoot "$(Build.SourcesDirectory)"

    - task: PowerShell@2
      displayName: 'Index documentation to Elastic Cloud'
      inputs:
        targetType: 'filePath'
        filePath: '$(Build.SourcesDirectory)/scripts/index-docs-to-elastic.ps1'
        arguments: >
          -DocsPath "$(Build.SourcesDirectory)/docs"
          -ElasticCloudId "$(ELASTIC_CLOUD_ID)"
          -ElasticApiKey "$(ELASTIC_API_KEY)"
          -IndexName "jupiter-documentation"
          -RepositoryName "Jupiter.Market.Elastic.Comparables"
      env:
        ELASTIC_CLOUD_ID: $(ELASTIC_CLOUD_ID)
        ELASTIC_API_KEY: $(ELASTIC_API_KEY)

    - script: |
        git config --global user.email "azure-pipelines@jupiter-market.com"
        git config --global user.name "Azure Pipeline"
        git add docs/
        if git diff --staged --quiet; then
          echo "No documentation changes to commit."
        else
          git commit -m "Update Docusaurus documentation [skip ci]"
          git push origin HEAD:main
        fi
      displayName: 'Commit and push generated documentation'

Permissions

• Ensure the Azure DevOps "Build Service" account has Contribute permission on the repository to allow automated pushes.

Troubleshooting

• If you see authentication or permission errors on git push, check the repository permissions for the build service account.
• If the Elastic indexing step fails, verify your ELASTIC_CLOUD_ID and ELASTIC_API_KEY variables.

References

• Azure Pipelines PowerShell Task Documentation
• Azure DevOps Pipeline Variables
• Elastic Cloud Documentation

---

Copy this article to your central documentation repository to help others set up and maintain the documentation pipeline.