Package: mkdocs-azure-pipelines
mkdocs-azure-pipelinesGenerate mkdocs documentation from Azure Pipelines yaml files.WhyWhen managing a large repository of pipeline template files, it can be difficult to keep track of what each template does and how to use it. This plugin aims to make it easier to document pipeline templates by generating markdown documentation from the template files themselves and adding it to a mkdocs site.Project GoalsPhase 1: Templates with parametersEstablish a syntax for title, about, example, outputs etc.Create a Python script which can process a pipelinetemplateand output a markdown file.In Progress: Convert to a real installable mkdocs plugin and publish to PyPi.Phase 2: PumlGenerate puml diagrams for the template which take conditions and expressions into consideration.Phase 3: Automatic parameter parsingMake the plugin document parameters based on the actual pipeline code, no need to use parameters-start and parameters-end tags.Phase 4: Automatic outputs parsingMake the plugin document outputs based on the actual pipeline code, no need to use outputs-start and outputs-end tags/section.Phase 5: Robustness and extrasSupport different syntaxes for parameters i.e both with and without "name" and "type" keys.Handle syntax errors gracefully with clear error messages.Phase 6: Any Azure PipelineMake the plugin work with any Azure Pipeline yaml file, not just templates. This means parsing variables, pool, trigger, resources etc.SyntaxThe idea is to use some kind of syntax to indicate what should be documented. This syntax should be easy to read and write, and should be able to be used in a way that doesn't break the pipeline. For simplicity the "marker"/"tag" will have a start point, end point and an identifier. The identifier will be used to determine what to do with the text between the start and end points. All text between the start and end points will be treated as markdown.ExampleThe following example shows how the syntax could look to document a pipeline template and what the resulting markdown would look like.# pytest-step.yml#:::title-start:::# Pytest pipeline step template#:::title-end:::#:::about-start:::# This pipeline template is used to run pytest.#:::about-end:::#:::example-start:::# steps:# - template: pip-build-and-publish-step.yml@templates#   parameters:#     python_version: '3.6'#:::example-end:::#:::outputs-start:::# **encouraging_message**: A message to encourage the user.#:::outputs-end:::#:::parameters-start:::parameters:-name:python_version# The version of Python to use.type:string-name:encouraging_message# The message to output.type:stringdefault:'Youlookgreattoday!'#:::parameters-end:::#:::code-start:::steps:-task:UsePythonVersion@0inputs:versionSpec:${{ parameters.python_version }}addToPath:truearchitecture:'x64'-bash:|python -m pip install --upgrade pippip install -r requirements.txtdisplayName:'Installdependencies'-bash:|pip install pytest pytest-azurepipelinespytestdisplayName:'Runpytest'-bash:|echo "##vso[task.setvariable variable=encouraging_message, isOutput=true]${{ parameters.encouraging_message }}"displayName:'Outputencouragingmessage'name:output_encouraging_message#:::code-end:::Would result in the following markdown when processed by the plugin:# Pytest pipeline step templateThis pipeline template is used to run pytest.## Parameters```yamlparameters:-name:python_version# The version of Python to use.type:string-name:encouraging_message# The message to output.type:stringdefault:'Youlookgreattoday!'```## Outputs**encouraging_message**: A message to encourage the user.## Example```yamlsteps:-template:pip-build-and-publish-step.yml@templatesparameters:python_version:'3.6'```## Code```yamlsteps:-task:UsePythonVersion@0inputs:versionSpec:${{ parameters.python_version }}addToPath:truearchitecture:'x64'-bash:|python -m pip install --upgrade pippip install -r requirements.txtdisplayName:'Installdependencies'-bash:|pip install pytest pytest-azurepipelinespytestdisplayName:'Runpytest'-bash:|echo "##vso[task.setvariable variable=encouraging_message, isOutput=true]You look great today!"displayName:'Outputencouragingmessage'name:output_encouraging_message```