Generate mkdocs documentation from Azure Pipelines yaml files.
When 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.
- Establish a syntax for title, about, example, outputs etc.
- Create a Python script which can process a pipeline template and output a markdown file.
- In Progress: Convert to a real installable mkdocs plugin and publish to PyPi.
- Generate puml diagrams for the template which take conditions and expressions into consideration.
- Make the plugin document parameters based on the actual pipeline code, no need to use parameters-start and parameters-end tags.
- Make the plugin document outputs based on the actual pipeline code, no need to use outputs-start and outputs-end tags/section.
- Support different syntaxes for parameters i.e both with and without "name" and "type" keys.
- Handle syntax errors gracefully with clear error messages.
- Make the plugin work with any Azure Pipeline yaml file, not just templates. This means parsing variables, pool, trigger, resources etc.
The 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.
The 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: string
default: 'You look great today!'
#:::parameters-end:::
#:::code-start:::
steps:
- task: UsePythonVersion@0
inputs:
versionSpec: ${{ parameters.python_version }}
addToPath: true
architecture: 'x64'
- bash: |
python -m pip install --upgrade pip
pip install -r requirements.txt
displayName: 'Install dependencies'
- bash: |
pip install pytest pytest-azurepipelines
pytest
displayName: 'Run pytest'
- bash: |
echo "##vso[task.setvariable variable=encouraging_message, isOutput=true]${{ parameters.encouraging_message }}"
displayName: 'Output encouraging message'
name: output_encouraging_message
#:::code-end:::Would result in the following markdown when processed by the plugin:
# Pytest pipeline step template
This pipeline template is used to run pytest.
## Parameters
```yaml
parameters:
- name: python_version # The version of Python to use.
type: string
- name: encouraging_message # The message to output.
type: string
default: 'You look great today!'
```
## Outputs
**encouraging_message**: A message to encourage the user.
## Example
```yaml
steps:
- template: pip-build-and-publish-step.yml@templates
parameters:
python_version: '3.6'
```
## Code
```yaml
steps:
- task: UsePythonVersion@0
inputs:
versionSpec: ${{ parameters.python_version }}
addToPath: true
architecture: 'x64'
- bash: |
python -m pip install --upgrade pip
pip install -r requirements.txt
displayName: 'Install dependencies'
- bash: |
pip install pytest pytest-azurepipelines
pytest
displayName: 'Run pytest'
- bash: |
echo "##vso[task.setvariable variable=encouraging_message, isOutput=true]You look great today!"
displayName: 'Output encouraging message'
name: output_encouraging_message
```Which would result in the following when built
🔔 Make sure that you have pipx installed on your environment.
pipx install pre-commit
pipx install toxLinting and formatting are handled by pre-commit. Tests and resources are in the tests directory written with pytest. Use tox to run both of them:
tox