Documenting Workflows

.. gha:workflow::

Document a github actions workflow

:path: (string)

The path to the workflow yaml file, relative to the repo root. If this is not provided, the workflow name must be present as an argument and there will be no autogenerated contents

:noexample:

If present, no usage example will be generated

Example

The following reusable workflow yaml file:

 1name: Pay Cow Taxes
 2
 3on:
 4  workflow_call:
 5    inputs:
 6      income:
 7        description: The cow's taxable income
 8        required: true
 9        type: number
10
11      paid-taxes:
12        description: How much the cow has paid in taxes
13        default: 0
14        type: number
15
16    outputs:
17      owed:
18        description: How much the cow owes
19        value: ${{ steps.calc.outputs.owed }}
20
21    secrets:
22      ssn:
23        required: false
24        description: The cow's social security number
25        type: string
26env:
27  TAX_RATE: 10
28
29jobs:
30  build:
31    runs-on: ubuntu-latest
32    steps:
33      - name: Calculate Taxes
34        id: calc
35        shell: bash
36        run: |
37          echo "owed=$(bc -l -e '(${{inputs.income}} * ${{env.TAX_RATE}} / 100) - ${{inputs.paid-taxes}}')" >> "$GITHUB_OUTPUT"
38
39      - name: Cow Say
40        uses: drewcassidy/sphinx-gha/.forgejo/actions/cowsay@main
41        with:
42          message: I have paid $${{ steps.calc.outputs.owed }} to the cow IRS

can be documented like so (using MyST markdown syntax):

```{gha:workflow}
:path: .forgejo/workflows/pay-cow-taxes.yml
```
workflow pay-cow-taxes

Example

- uses: 
    https://git.offworldcolonies.nexus/drewcassidy/sphinx-gha/.forgejo/workflows/pay-cow-taxes.yml@main

Inputs

input income
Required:
True
Type:
number

The cow’s taxable income

input paid-taxes
Default:
0
Type:
number

How much the cow has paid in taxes

Secrets

secret ssn
Required:
False
Type:
string

The cow’s social security number

Outputs

output owed

How much the cow owes