Skip to content

docs: update action documentation #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hoverkraft-bot merged 1 commit into from
Sep 22, 2025
Merged

docs: update action documentation #127

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 2 additions & 124 deletions packages/docs/content/integrations/github-action.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ CI Dokumentor can be used directly as a GitHub Action in your workflows, making
## Usage

```yaml
- uses: hoverkraft-tech/ci-dokumentor@15c7f84ea2d28aec8be9582763d88f6a3945f1c6 # main
- uses: hoverkraft-tech/ci-dokumentor@2cfa34821d58c4814fe8056a4a001fbcd2c21be2 # main
with:
# Source manifest file path to handle (e.g. `action.yml`, `.github/workflows/ci.yml`).
# This input is required.
Expand Down Expand Up @@ -100,126 +100,4 @@ CI Dokumentor can be used directly as a GitHub Action in your workflows, making
- [Developers Guide](../developers/ci-cd.md) - Advanced CI/CD integration patterns

<!-- secrets:start -->
<!-- secrets:end --><!-- examples:start -->

### Generate Documentation for Workflows

```yaml
- name: Generate Workflow Documentation
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: '.github/workflows/ci.yml'
```

### Advanced Usage with All Options

The CLI accepts a single `--source <file>` per invocation. To generate documentation for multiple files in a workflow, run the action multiple times or script the Docker/CLI call for each file. Example using a shell step to process multiple manifest files:

```yaml
- name: Generate Enhanced Documentation
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'
output: 'docs/README.md'
repository: 'github'
cicd: 'github-actions'
include-sections: 'inputs,outputs,runs'
exclude-sections: 'examples'
format-link: 'full'
```

### Dry-run Example

To preview changes without modifying files, set the `dry-run` input to `true`. The action will pass `--dry-run` to the CLI and the core generator will produce a diff instead of writing files.

```yaml
- name: Generate Documentation (dry-run)
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'
dry-run: 'true'
```

### URL Link Formatting Examples

Control how bare URLs in your documentation are formatted:

```yaml
# Transform URLs to autolinks (default when option used)
- name: Generate with Autolinks
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'
format-link: 'auto'
# URLs like https://example.com become <https://example.com>

# Transform URLs to full markdown links
- name: Generate with Full Links
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'
format-link: 'full'
# URLs like https://example.com become [https://example.com](https://example.com)

# Disable URL transformation
- name: Generate with Raw URLs
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'
format-link: 'false'
# URLs remain as bare text: https://example.com
```

## Complete Workflow Examples

### Auto-Commit Documentation

This workflow automatically generates and commits documentation when CI/CD files change:

```yaml title=".github/workflows/auto-docs.yml"
name: Auto-Generate Documentation

on:
push:
branches: [main]
paths:
- 'action.yml'
- '.github/workflows/*.yml'

permissions:
contents: write

jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
token: ${{ secrets.GITHUB_TOKEN }}

- name: Generate Documentation
uses: hoverkraft-tech/ci-dokumentor@v1
with:
source: 'action.yml'

- name: Check for Documentation Changes
id: verify-changed-files
run: |
if [ -n "$(git status --porcelain README.md)" ]; then
echo "changed=true" >> $GITHUB_OUTPUT
else
echo "changed=false" >> $GITHUB_OUTPUT
fi

- name: Commit Documentation Updates
if: steps.verify-changed-files.outputs.changed == 'true'
run: |
git config --local user.email "action@github.com"
git config --local user.name "GitHub Action"
git add README.md
git commit -m "docs: update action documentation\n[skip ci]"
git push
```

<!-- examples:end -->
<!-- secrets:end -->
Loading