Generate docs from an Azure Pipelines YAML file
Project description
mkdocs-azure-pipelines
Generate mkdocs documentation from Azure Pipelines yaml files.
Why
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.
Project Goals
Phase 1: Templates with parameters
- 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.
Phase 2: Puml
- Generate puml diagrams for the template which take conditions and expressions into consideration.
Phase 3: Automatic parameter parsing
- Make the plugin document parameters based on the actual pipeline code, no need to use parameters-start and parameters-end tags.
Phase 4: Automatic outputs parsing
- Make 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 extras
- Support 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 Pipeline
- Make the plugin work with any Azure Pipeline yaml file, not just templates. This means parsing variables, pool, trigger, resources etc.
Syntax
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.
Example
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
```
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocs-azure-pipelines-0.0.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e723efe3523696a20790846a16c8581b79f7da8ffb380dd2e1fbfa71495a79ac |
|
MD5 | 6019ba9b08da63bb1518ef2b42cc0cfb |
|
BLAKE2b-256 | 0ff53023f2b67399003417229ca7150c2241b6d8193e5b9f7b591acefa422eb8 |
Hashes for mkdocs_azure_pipelines-0.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7f4eb4bb7312fd6c38f1902faf40d4060aa856777d51970882b30376ee1afdd3 |
|
MD5 | 6f8d2eb8228dcffbdb85b6eb70e4429f |
|
BLAKE2b-256 | a9ef0bc31b688fe1b30ab9592e7ad58c65b50fe5fdc342f1d9b827fef17d7568 |