@pipelinedoc/cli

The CLI for generating docs for your YAML pipeline template files. Sample generated docs.

Install

Install with NPM:

npm install -g @pipelinedoc/cli

or install with yarn:

yarn global add @pipelinedoc/cli

Commands

Generate

Generate markdown docs from your templates. Currently only supports Azure Pipelines templates.

pipelinedoc generate <files> [options]

Arguments

• files: specify a space-separated list of glob patterns to match your pipeline templates.

Options

• --out-dir, -o: specify the directory to output the files to. Defaults to ./docs.
• --strict: in strict mode, warnings are considered errors and the CLI will exit with a non-zero exit code.
• --repo-identifier: the repo identifier for importing templates in Azure Pipelines. Defaults to templates.
• --generate-frontmatter: generate YAML frontmatter on each .md file with machine-readable metadata.
• --assert-unstaged: exit with a non-zero exit if there are unstaged docs files after generating docs. Useful for pre-commit Git hooks to ensure your docs are up-to-date.

Properties file

In order to fully document templates, pipelinedoc requires a second "properties" file for each template. This is because adding extra meta properties to templates is disallowed by the template parsers.

To document a template with a properties file, create a file next to your template file with the same name but with the .properties.yml extension (you can also use .yaml and .json if you prefer). For example, if I had a my-template.yml template, I would create a my-template.properties.yml properties file.

Supported properties

• name: the display name of the template.
• version: the version of the template. Strings and numbers are supported.
• description: the description of the template. Markdown is supported.
• category: a category to assign the template to. Used for grouping templates in the index.md doc
• usageStyle: the style of the usage example, either 'insert' or 'extend'. If 'insert', uses the template insertion syntax, and if 'extend', uses the template extension syntax. Defaults to 'insert'.
• deprecated: whether or not the template is deprecated. Implicitly true if deprecatedWarning is supplied.
• deprecatedWarning: a message to include with the deprecated warning. Markdown is supported.
• parameters.<parameter name>.description: the description of the parameter. Markdown is supported.
• examples.<index>.title: the title of a usage example. Markdown is supported.
• examples.<index>.description: the description of a usage example. Markdown is supported.
• examples.<index>.example: the example YAML object. Examples may include variables in keys or values using the syntax $<variableName>. The following variables are available:
  • templatePath: the template path (including repo identifier) to include the template with.

Example

name: My template
version: 1
description: |
  This is my _fancy_ description with **markdown**!
category: Utils
parameters:
  myParameter:
    description: |
      This is my parameter with the name `myParameter`.
examples:
  - example:
      stages:
        - stage: my_stage
          jobs:
            - template: $<templatePath>
              parameters:
                myParameter: the best way to use me
  - title: Example title
    description: Some more details here.
    example:
      jobs:
        - template: $<templatePath>
          parameters:
            myParameter: another option