# Documenting Workflows

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

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

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

## Example

The following reusable workflow yaml file:

```{literalinclude} ../.forgejo/workflows/pay-cow-taxes.yml
:language: yaml
:linenos:
```

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

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