mkdocstrings-github

A GitHub Actions handler for mkdocstrings.

Features

• 📝 Automatic Example Signature: Displays an example call signature alongside the description. The version shown can be the latest release, latest major, current reference, or any custom string.
• ✨ Enhanced Markdown Descriptions: All description elements are parsed using a markdown parser, enabling comprehensive formatting and rich documentation capabilities.
• 🧩 Individual Parameter Hyperlinks: Each action or workflow parameter—including inputs, outputs, and secrets—receives a unique HTML id, facilitating direct linking to specific parameter documentation.
• 🔒 Automated Permission Aggregation: For reusable workflows, if permissions are specified at the job level rather than the workflow level, the required final permissions are automatically determined and displayed in the signature.
• 🔗 Parameter cross-linking: Link to other parameters of the action or workflow via a simple Markdown syntax.

Example

The following action.yaml file

action.yaml

name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

will be shown in the documentation as:

Example action

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs:

Name	Description	Default
input-string	A string input parameter
input-number	A numeric input parameter	42
input-boolean	A boolean input parameter	false

Outputs:

Name	Description
output-string	A string output from the action
output-number	A numeric output from the action