Wondering what’s next for npm?Check out our public roadmap! »

    @pipelinedoc/cli
    TypeScript icon, indicating that this package has built-in type declarations

    1.8.0 • Public • Published

    @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

    Keywords

    none

    Install

    npm i @pipelinedoc/cli

    DownloadsWeekly Downloads

    7

    Version

    1.8.0

    License

    MIT

    Unpacked Size

    87.3 kB

    Total Files

    32

    Last publish

    Collaborators

    • avatar