# Documenting Actions

````{rst:directive} gha:action
Document a github actions action

```{rst:directive:option} path
:type: 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
```

```{rst:directive:option} noexample
If present, no usage example will be generated
```

```{rst:directive:option} 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:

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

## Example

The following action yaml file:

```{literalinclude} ../.github/actions/cowsay/action.yaml
:language: yaml
:linenos:
```

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

````{example}
```{gha:action}
:path: .github/actions/cowsay
```
````