Skip to content

Commit 8214674

Browse files
alexey1312alexey1312
authored
Merge pull request #31 from alexey1312/alexey1312/add-docc-doc
Add DocC documentation and GitHub Pages deployment
2 parents 736845d + 04a4e8b commit 8214674

File tree

11 files changed

+694
-4
lines changed

11 files changed

+694
-4
lines changed

‎.github/workflows/deploy-docc.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: Deploy DocC
2+
3+
on:
4+
push:
5+
branches: ["master"]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: true
16+
17+
jobs:
18+
deploy:
19+
environment:
20+
name: github-pages
21+
url: ${{ steps.deployment.outputs.page_url }}
22+
runs-on: macos-latest
23+
timeout-minutes: 30
24+
steps:
25+
- uses: actions/checkout@v5
26+
27+
- name: Build DocC
28+
run: |
29+
swift package --allow-writing-to-directory docs \
30+
generate-documentation --target xcsift \
31+
--disable-indexing \
32+
--transform-for-static-hosting \
33+
--hosting-base-path xcsift \
34+
--output-path docs
35+
echo '<script>window.location.href += "/documentation/xcsift"</script>' > docs/index.html
36+
37+
- uses: actions/upload-pages-artifact@v4
38+
with:
39+
path: 'docs'
40+
41+
- name: Deploy to GitHub Pages
42+
id: deployment
43+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,4 @@ DerivedData/
66
.swiftpm/configuration/registries.json
77
.swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata
88
.netrc
9+
/docs

‎CLAUDE.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ swift test
2222
### Formatting
2323
**IMPORTANT:** Always run before committing changes:
2424
```bash
25-
swift format --recursive --in-place Sources Tests
25+
swift format --recursive --in-place .
2626
```
2727

2828
### Installation
@@ -408,3 +408,27 @@ When running on GitHub Actions (`GITHUB_ACTIONS=true`), xcsift automatically app
408408
- name: Annotations only (no JSON/TOON)
409409
run: xcodebuild build 2>&1 | xcsift -f github-actions
410410
```
411+
412+
## Documentation Maintenance
413+
414+
**IMPORTANT:** When modifying public API, CLI flags, or features, you MUST update the corresponding DocC documentation in `Sources/xcsift.docc/`.
415+
416+
Documentation files to update:
417+
- `xcsift.md` - Main overview and Topics structure
418+
- `GettingStarted.md` - Installation and basic usage
419+
- `Usage.md` - CLI flags and options reference
420+
- `OutputFormats.md` - JSON/TOON/GitHub Actions format details
421+
- `CodeCoverage.md` - Coverage feature documentation
422+
423+
### Previewing Documentation Locally
424+
425+
**For Claude:** You cannot run the preview server (it's interactive/long-running). Ask the user to run it manually.
426+
427+
**For user:** Run in a separate terminal:
428+
```bash
429+
swift package --disable-sandbox preview-documentation --target xcsift
430+
```
431+
Opens at: http://localhost:8080/documentation/xcsift
432+
433+
**Note:** The `docs/` folder contains pre-generated documentation for GitHub Pages with `--hosting-base-path xcsift`. Do NOT use a simple HTTP server (like `python3 -m http.server`) to serve `docs/` directly — it won't handle the `/xcsift/` base path routing.
434+

‎Package.resolved‎

Lines changed: 19 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Package.swift‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ let package = Package(
1313
dependencies: [
1414
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
1515
.package(url: "https://github.com/toon-format/toon-swift.git", from: "0.3.0"),
16+
.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.4.5"),
1617
],
1718
targets: [
1819
.executableTarget(

‎README.md‎

Lines changed: 38 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
[![Swift-versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fldomaradzki%2Fxcsift%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/ldomaradzki/xcsift)
66
[![CI](https://github.com/ldomaradzki/xcsift/actions/workflows/ci.yml/badge.svg)](https://github.com/ldomaradzki/xcsift/actions/workflows/ci.yml)
77
[![Release](https://github.com/ldomaradzki/xcsift/actions/workflows/release.yml/badge.svg)](https://github.com/ldomaradzki/xcsift/actions/workflows/release.yml)
8+
[![Docs](https://github.com/ldomaradzki/xcsift/actions/workflows/deploy-docc.yml/badge.svg)](https://ldomaradzki.github.io/xcsift/documentation/xcsift)
89
[![License](https://img.shields.io/github/license/ldomaradzki/xcsift.svg)](LICENSE.md)
910

1011
![Example](.github/images/example.png)
@@ -475,18 +476,53 @@ jobs:
475476

476477
## Development
477478

479+
### Building
480+
481+
```bash
482+
swift build
483+
swift build -c release
484+
```
485+
478486
### Running Tests
479487

480488
```bash
481489
swift test
482490
```
483491

484-
### Building
492+
### Formatting
493+
494+
**Required before committing:**
485495

486496
```bash
487-
swift build
497+
swift format --recursive --in-place .
498+
```
499+
500+
### Documentation
501+
502+
Generate DocC documentation locally:
503+
504+
```bash
505+
# Build static documentation
506+
swift package --allow-writing-to-directory docs \
507+
generate-documentation --target xcsift \
508+
--disable-indexing \
509+
--transform-for-static-hosting \
510+
--hosting-base-path xcsift \
511+
--output-path docs
512+
513+
# Preview documentation (opens in browser at http://localhost:8080)
514+
swift package --disable-sandbox preview-documentation --target xcsift
488515
```
489516

517+
Documentation source files are in `Sources/xcsift.docc/`:
518+
- `xcsift.md` — Main overview
519+
- `GettingStarted.md` — Installation guide
520+
- `Usage.md` — CLI reference
521+
- `OutputFormats.md` — Format details
522+
- `CodeCoverage.md` — Coverage feature
523+
524+
**Production URL:** [ldomaradzki.github.io/xcsift](https://ldomaradzki.github.io/xcsift/documentation/xcsift)
525+
490526
## License
491527

492528
MIT License

‎Sources/xcsift.docc/CodeCoverage.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Code Coverage
2+
3+
Automatic code coverage conversion and reporting.
4+
5+
## Overview
6+
7+
xcsift automatically converts coverage data from both Swift Package Manager and xcodebuild formats without requiring manual llvm-cov or xccov commands.
8+
9+
## Enabling Coverage
10+
11+
### Swift Package Manager
12+
13+
```bash
14+
swift test --enable-code-coverage 2>&1 | xcsift --coverage
15+
```
16+
17+
### xcodebuild
18+
19+
```bash
20+
xcodebuild test -enableCodeCoverage YES 2>&1 | xcsift --coverage
21+
```
22+
23+
## Output Modes
24+
25+
### Summary-Only (Default)
26+
27+
By default, only the coverage percentage is included for token efficiency:
28+
29+
```json
30+
{
31+
"summary": {
32+
"coverage_percent": 85.5
33+
}
34+
}
35+
```
36+
37+
### Details Mode
38+
39+
Use `--coverage-details` for per-file breakdown:
40+
41+
```bash
42+
swift test --enable-code-coverage 2>&1 | xcsift --coverage --coverage-details
43+
```
44+
45+
Output:
46+
```json
47+
{
48+
"summary": {
49+
"coverage_percent": 85.5
50+
},
51+
"coverage": {
52+
"line_coverage": 85.5,
53+
"files": [
54+
{
55+
"path": "/path/to/ViewController.swift",
56+
"name": "ViewController.swift",
57+
"line_coverage": 92.5,
58+
"covered_lines": 37,
59+
"executable_lines": 40
60+
}
61+
]
62+
}
63+
}
64+
```
65+
66+
## Auto-Detection
67+
68+
xcsift automatically searches for coverage data in common locations:
69+
70+
### SPM Paths
71+
- `.build/debug/codecov`
72+
- `.build/arm64-apple-macosx/debug/codecov`
73+
- `.build/x86_64-apple-macosx/debug/codecov`
74+
75+
### xcodebuild Paths
76+
- `~/Library/Developer/Xcode/DerivedData/**/*.xcresult`
77+
- `./**/*.xcresult`
78+
79+
### Custom Path
80+
81+
Override auto-detection with `--coverage-path`:
82+
83+
```bash
84+
swift test --enable-code-coverage 2>&1 | xcsift --coverage --coverage-path .build/arm64-apple-macosx/debug/codecov
85+
```
86+
87+
## Automatic Conversion
88+
89+
### SPM Coverage
90+
91+
xcsift performs automatic conversion:
92+
1. Finds `.profraw` files
93+
2. Locates test binary
94+
3. Runs `llvm-profdata merge`
95+
4. Runs `llvm-cov export`
96+
97+
### xcodebuild Coverage
98+
99+
xcsift handles xcresult bundles:
100+
1. Finds latest `.xcresult` bundle
101+
2. Runs `xcrun xccov view --report --json`
102+
3. Extracts target from build output
103+
4. Filters coverage to tested target only
104+
105+
## Target Filtering
106+
107+
For xcodebuild, xcsift automatically extracts the tested target name from stdout and filters coverage to that target only. This prevents unrelated framework coverage from cluttering the output.
108+
109+
If no matching coverage data is found, a warning is printed to stderr.
110+
111+
## Platform Support
112+
113+
| Platform | Coverage Support |
114+
|----------|-----------------|
115+
| macOS 15+ | Full support |
116+
| Linux (Swift 6.0+) | Not available (macOS tools required) |
117+
118+
## TOON Format
119+
120+
Coverage works with TOON format:
121+
122+
```bash
123+
swift test --enable-code-coverage 2>&1 | xcsift -f toon --coverage
124+
```
125+
126+
Summary-only TOON output:
127+
```toon
128+
status: succeeded
129+
summary:
130+
errors: 0
131+
warnings: 0
132+
failed_tests: 0
133+
passed_tests: 42
134+
coverage_percent: 85.5
135+
```

0 commit comments

Comments
 (0)