Skip to content

Commit e2c0bb3

Browse files
promptless[bot]promptless[bot]
authored
Add CI and Integrations documentation pages
1 parent f72d1ef commit e2c0bb3

File tree

3 files changed

+251
-0
lines changed

3 files changed

+251
-0
lines changed

‎fern/docs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,10 @@ navigation:
120120
path: pages/docs/get-started/create-your-first-test.mdx
121121
- page: Sample tests
122122
path: pages/docs/get-started/sample-tests.mdx
123+
- page: CI
124+
path: pages/docs/get-started/ci.mdx
125+
- page: Integrations
126+
path: pages/docs/get-started/integrations.mdx
123127
- page: Resources
124128
path: pages/docs/get-started/resources.mdx
125129

‎fern/pages/docs/get-started/ci.mdx‎

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
---
2+
title: CI integration
3+
sidebar-title: CI
4+
---
5+
6+
Run Doc Detective in continuous integration (CI) pipelines using the GitHub Action. Test your docs on every push or pull request.
7+
8+
## Set up the GitHub Action
9+
10+
To add Doc Detective to your GitHub Actions workflow, create a YAML file in your `.github/workflows` directory:
11+
12+
```yaml
13+
name: doc-detective
14+
on: [pull_request]
15+
16+
jobs:
17+
runTests:
18+
runs-on: ubuntu-latest
19+
steps:
20+
- uses: actions/checkout@v4
21+
- uses: doc-detective/github-action@v1
22+
```
23+
24+
This runs Doc Detective tests whenever a pull request is opened or updated.
25+
26+
## Configuration options
27+
28+
Customize the action with inputs by adding a `with` key to the `uses` block:
29+
30+
```yaml
31+
- uses: doc-detective/github-action@v1
32+
with:
33+
version: latest
34+
input: ./docs
35+
config: .doc-detective.json
36+
```
37+
38+
### Common inputs
39+
40+
| Input | Default | Description |
41+
|-------|---------|-------------|
42+
| `version` | `latest` | Doc Detective version (npm version or tag) |
43+
| `working_directory` | Repository root | Directory to run the action in |
44+
| `config` | None | Path to configuration file |
45+
| `input` | None | Path to input file or directory (overrides config) |
46+
| `command` | `runTests` | Command to run (`runTests` or `runCoverage`) |
47+
| `exit_on_fail` | `false` | Exit with non-zero code if tests fail |
48+
49+
## Create pull requests automatically
50+
51+
Doc Detective might update files in your repository when it runs—like refreshing screenshots or updating command output. You can automatically create a pull request with these changes.
52+
53+
```yaml
54+
name: doc-detective
55+
on:
56+
schedule:
57+
- cron: '0 0 * * *' # Run daily at midnight
58+
59+
jobs:
60+
runTests:
61+
runs-on: ubuntu-latest
62+
permissions:
63+
contents: write
64+
pull-requests: write
65+
66+
steps:
67+
- uses: actions/checkout@v4
68+
- uses: doc-detective/github-action@v1
69+
with:
70+
create_pr_on_change: true
71+
pr_title: Doc Detective found changes
72+
pr_labels: doc-detective,for-review
73+
```
74+
75+
<Note>
76+
77+
You must enable GitHub Actions to create pull requests for your repository. Go to **Settings** > **Actions** > **General** and select **Allow GitHub Actions to create and approve pull requests**.
78+
79+
</Note>
80+
81+
### Pull request options
82+
83+
| Input | Default | Description |
84+
|-------|---------|-------------|
85+
| `create_pr_on_change` | `false` | Create a PR if files change |
86+
| `pr_branch` | `doc-detective-{DATE}` | Branch name for the PR |
87+
| `pr_title` | `Doc Detective Changes` | PR title |
88+
| `pr_body` | See default | PR description (`$RUN_URL` inserts the workflow URL) |
89+
| `pr_labels` | `doc-detective` | Comma-separated labels |
90+
| `pr_assignees` | None | Comma-separated usernames to assign |
91+
| `pr_reviewers` | None | Comma-separated usernames to request reviews |
92+
93+
## Create issues on test failure
94+
95+
If tests fail, you can automatically create a GitHub issue to track the problem. You can also trigger [integrations](/docs/get-started/integrations) to investigate and fix failures.
96+
97+
```yaml
98+
name: doc-detective
99+
on: [pull_request]
100+
101+
jobs:
102+
runTests:
103+
runs-on: ubuntu-latest
104+
permissions:
105+
contents: read
106+
issues: write
107+
steps:
108+
- uses: actions/checkout@v4
109+
- uses: doc-detective/github-action@v1
110+
with:
111+
create_issue_on_fail: true
112+
issue_title: Doc Detective found documentation issues
113+
integrations: claude
114+
```
115+
116+
### Issue options
117+
118+
| Input | Default | Description |
119+
|-------|---------|-------------|
120+
| `create_issue_on_fail` | `false` | Create an issue if tests fail |
121+
| `issue_title` | `Doc Detective Failure` | Issue title |
122+
| `issue_body` | See default | Issue body (`$RESULTS` inserts test results, `$RUN_URL` inserts workflow URL) |
123+
| `issue_labels` | `doc-detective` | Comma-separated labels |
124+
| `issue_assignees` | None | Comma-separated usernames to assign |
125+
| `integrations` | None | Comma-separated integrations to trigger (see [Integrations](/docs/get-started/integrations)) |
126+
| `prompt` | See default | Custom prompt to pass to integrations |
127+
128+
## Action outputs
129+
130+
The action provides outputs you can use in subsequent workflow steps:
131+
132+
| Output | Description |
133+
|--------|-------------|
134+
| `results` | JSON-formatted test results |
135+
| `pull_request_url` | URL of created PR (if applicable) |
136+
| `issue_url` | URL of created issue (if applicable) |
137+
138+
Example using outputs:
139+
140+
```yaml
141+
- uses: doc-detective/github-action@v1
142+
id: doc-detective
143+
- run: echo "Results: ${{ steps.doc-detective.outputs.results }}"
144+
```
145+
146+
## Browser modes
147+
148+
On Ubuntu runners, the action only supports headless browser mode. Chrome and Firefox contexts automatically fall back to headless mode when necessary.
149+
150+
If your tests require non-headless mode (like video recording with `startRecording`), use macOS or Windows runners instead:
151+
152+
```yaml
153+
jobs:
154+
runTests:
155+
runs-on: macos-latest # or windows-latest
156+
steps:
157+
- uses: actions/checkout@v4
158+
- uses: doc-detective/github-action@v1
159+
```

‎fern/pages/docs/get-started/integrations.mdx‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Integrations
3+
sidebar-title: Integrations
4+
---
5+
6+
When Doc Detective tests fail in CI, you can trigger AI-powered integrations to investigate failures and suggest fixes. These integrations respond to GitHub issues created when tests fail.
7+
8+
## How integrations work
9+
10+
1. Configure the GitHub Action to create issues on test failure (`create_issue_on_fail: true`).
11+
2. Specify which integrations to trigger in the `integrations` input.
12+
3. When tests fail, Doc Detective creates a GitHub issue and mentions the specified integrations.
13+
4. Each integration analyzes the test results and provides suggestions.
14+
15+
## Supported integrations
16+
17+
| Integration | Description |
18+
|-------------|-------------|
19+
| `claude` | Anthropic's Claude AI assistant |
20+
| `copilot` | GitHub Copilot |
21+
| `dosu` | Dosu AI assistant |
22+
| `promptless` | Promptless documentation automation |
23+
| `doc-sentinel` | Doc Sentinel documentation monitoring |
24+
| `opencode` | OpenCode AI assistant |
25+
26+
## Using integrations
27+
28+
To trigger integrations, add them to your GitHub Actions workflow:
29+
30+
```yaml
31+
name: doc-detective
32+
on: [pull_request]
33+
34+
jobs:
35+
runTests:
36+
runs-on: ubuntu-latest
37+
permissions:
38+
contents: read
39+
issues: write
40+
steps:
41+
- uses: actions/checkout@v4
42+
- uses: doc-detective/github-action@v1
43+
with:
44+
create_issue_on_fail: true
45+
integrations: claude,copilot
46+
```
47+
48+
Specify multiple integrations by separating them with commas.
49+
50+
### Custom prompts
51+
52+
Use the `prompt` input to customize the instructions sent to integrations:
53+
54+
```yaml
55+
- uses: doc-detective/github-action@v1
56+
with:
57+
create_issue_on_fail: true
58+
integrations: claude
59+
prompt: "Analyze these test failures and suggest specific fixes for the documentation."
60+
```
61+
62+
The default prompt is: "Investigate potential causes of the failures reported in this Doc Detective test output and suggest fixes."
63+
64+
## Integration behaviors
65+
66+
Each integration responds differently when triggered:
67+
68+
| Integration | Behavior |
69+
|-------------|----------|
70+
| `claude` | Doc Detective adds an `@claude` mention to the issue. Claude analyzes test results and suggests fixes. |
71+
| `copilot` | The issue is automatically assigned to GitHub Copilot instead of being mentioned in a collapsible section. |
72+
| `dosu` | Doc Detective mentions Dosu in the issue to analyze context and provide suggestions. |
73+
| `promptless` | Promptless analyzes test failures and can automatically create documentation updates. |
74+
| `doc-sentinel` | Doc Detective mentions Doc Sentinel to help monitor and identify documentation issues. |
75+
| `opencode` | Doc Detective mentions OpenCode to analyze failures and suggest code-related fixes. |
76+
77+
<Note>
78+
79+
Each integration requires setup in your repository before use:
80+
81+
- **Claude**: Install the Claude GitHub app.
82+
- **Copilot**: Enable GitHub Copilot and configure it for issue handling.
83+
- **Dosu**: Install the Dosu app.
84+
- **Promptless**: Connect your repository to Promptless.
85+
- **Doc Sentinel**: Configure Doc Sentinel.
86+
- **OpenCode**: Install OpenCode.
87+
88+
</Note>

0 commit comments

Comments
 (0)