Documenting Actions

.. gha:action::

Document a github actions action

:path: (string)

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

:noexample:

If present, no usage example will be generated

:nodescription:

If present, the description from the yaml file will not be used

Documentation Metadata

The usual description and default values in the action will be used to generate documentation, however additional keys can provide richer documentation. These are added directly to the action file, and all keys use the x- prefix to avoid violating the schema.

Example Data

the x-example-name value is used as the step name in the auto-generated usage example. All environment variables and inputs have the example/x-example key to provide a usage example value for the auto-generated usage example.

Environment Variables

If your action uses any environment variables, you can describe them in the x-env top level dictionary like so:

x-env:
  COWPATH:
    description: if present, path used to search for cowfiles.
    example: ./my-cow-files/

Example

The following action yaml file:

 1name: Cowsay
 2description: |
 3  configurable speaking/thinking cow (and a bit more)
 4  
 5  Generates an ASCII picture of a cow saying something provided by the user.
 6
 7branding:
 8  icon: message-circle
 9  color: green
10
11x-example-name: 'Make bunny say moo'
12x-env:
13  COWPATH:
14    description: if present, path used to search for cowfiles.
15
16inputs:
17  message:
18    description: "what the cow should say"
19    required: True
20    x-example: 'moo'
21
22  cowfile:
23    description: cowfile to use. Must be present in `COWPATH`
24    default: 'default'
25    x-example: 'bunny'
26
27  dead:
28    description: causes the cow to appear dead
29    default: 'False'
30    deprecationMessage: 'Please do not kill the cow'
31
32outputs:
33  stdout:
34    description: "Cowsay output"
35    value: ${{ steps.cowsay.outputs.stdout}}
36
37runs:
38  using: "composite"
39  steps:
40    - name: Setup Cowsay
41      shell: bash
42      run: |
43        sudo apt update
44        sudo apt install cowsay
45
46    - name: Run Cowsay
47      shell: bash
48      id: cowsay
49      run: |
50        echo "stdout<<EO🐄" >> "$GITHUB_OUTPUT"
51        cowsay -f ${{ inputs.cowfile }} ${{ inputs.dead && '-d' }} ${{inputs.message}} | tee >> "$GITHUB_OUTPUT"
52        echo "EO🐄" >> "$GITHUB_OUTPUT"

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

```{gha:action}
:path: .forgejo/actions/cowsay
```
action cowsay

configurable speaking/thinking cow (and a bit more)

Generates an ASCII picture of a cow saying something provided by the user.

Example

- name: Make bunny say moo
  uses: 
    https://git.offworldcolonies.nexus/drewcassidy/sphinx-gha/.forgejo/actions/cowsay@1.0.1
  with:
    message: moo
    cowfile: bunny

Inputs

input message
Required:
True

what the cow should say

input cowfile
Default:
default

cowfile to use. Must be present in COWPATH

input dead

Deprecated

Please do not kill the cow
Default:
False

causes the cow to appear dead

Outputs

output stdout

Cowsay output

Environment Variables

env COWPATH

if present, path used to search for cowfiles.